zendesk

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name ZENDESK_API_TOKEN` or `zero doctor check-connector --url https://your-subdomain.zendesk.com/api/v2/tickets.json --method GET`

## How to Use

All examples assume environment variables are set.

**Base URL**: `https://{subdomain}.zendesk.com/api/v2/`

**Authentication**: API Token via `-u` flag
```bash
-u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
```

**Note**: The `-u` flag automatically handles Base64 encoding for you.

## Core APIs

### 1. List Tickets

Get all tickets (paginated):

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.tickets[] | {id, subject, status, priority}
```

With pagination:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json?page=1&per_page=50" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
```

### 2. Get Ticket

Retrieve a specific ticket:

```bash
TICKET_ID="123"

curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
```

### 3. Create Ticket

Create a new support ticket:

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "subject": "My printer is on fire!",
    "comment": {
      "body": "The smoke is very colorful."
    },
    "priority": "urgent"
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

Create ticket with more details:

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "subject": "Need help with account",
    "comment": {
      "body": "I cannot access my account settings."
    },
    "priority": "high",
    "status": "open",
    "type": "problem",
    "tags": ["account", "access"]
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 4. Update Ticket

Update an existing ticket:

```bash
TICKET_ID="123"
```

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "status": "solved",
    "comment": {
      "body": "Issue has been resolved. Thank you!",
      "public": true
    }
  }
}
```

Then run:

```bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

Change priority and assignee:

```bash
TICKET_ID="123"
ASSIGNEE_ID="456"
```

Write to `/tmp/zendesk_request.json`:

```json
{
  "ticket": {
    "priority": "high",
    "assignee_id": ASSIGNEE_ID_PLACEHOLDER
  }
}
```

Then run:

```bash
sed -i '' "s/ASSIGNEE_ID_PLACEHOLDER/${ASSIGNEE_ID}/" /tmp/zendesk_request.json

curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 5. Delete Ticket

Permanently delete a ticket:

```bash
TICKET_ID="123"

curl -s -X DELETE "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/${TICKET_ID}.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
```

### 6. Create Multiple Tickets

Bulk create tickets:

Write to `/tmp/zendesk_request.json`:

```json
{
  "tickets": [
    {
      "subject": "Ticket 1",
      "comment": {
        "body": "First ticket"
      }
    },
    {
      "subject": "Ticket 2",
      "comment": {
        "body": "Second ticket"
      }
    }
  ]
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/tickets/create_many.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 7. List Users

Get all users:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email, role}
```

### 8. Get Current User

Get authenticated user details:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"
```

### 9. Create User

Create an end-user:

Write to `/tmp/zendesk_request.json`:

```json
{
  "user": {
    "name": "John Customer",
    "email": "[email protected]",
    "role": "end-user"
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

Create an agent:

Write to `/tmp/zendesk_request.json`:

```json
{
  "user": {
    "name": "Jane Agent",
    "email": "[email protected]",
    "role": "agent"
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 10. Update User

Update user information:

```bash
USER_ID="456"
```

Write to `/tmp/zendesk_request.json`:

```json
{
  "user": {
    "name": "Updated Name",
    "phone": "+1234567890"
  }
}
```

Then run:

```bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/${USER_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 11. Search Users

Search for users by query:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/search.json?query=john" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.users[] | {id, name, email}
```

### 12. List Organizations

Get all organizations:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.organizations[] | {id, name, domain_names}
```

### 13. Create Organization

Create a new organization:

Write to `/tmp/zendesk_request.json`:

```json
{
  "organization": {
    "name": "Acme Inc",
    "domain_names": ["acme.com", "acmeinc.com"],
    "details": "Important customer"
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 14. Update Organization

Update organization details:

```bash
ORG_ID="789"
```

Write to `/tmp/zendesk_request.json`:

```json
{
  "organization": {
    "name": "Acme Corporation",
    "notes": "Premium customer since 2020"
  }
}
```

Then run:

```bash
curl -s -X PUT "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/organizations/${ORG_ID}.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 15. List Groups

Get all agent groups:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" | jq '.groups[] | {id, name}
```

### 16. Create Group

Create a new agent group:

Write to `/tmp/zendesk_request.json`:

```json
{
  "group": {
    "name": "Support Team"
  }
}
```

Then run:

```bash
curl -s -X POST "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/groups.json" -H "Content-Type: application/json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -d @/tmp/zendesk_request.json
```

### 17. Search API

Search for open tickets:

Write to `/tmp/zendesk_query.txt`:

```
type:ticket status:open
```

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zendesk_query.txt" | jq '.results[] | {id, subject, status}
```

Search for high priority tickets:

```bash
curl -s "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/search.json" -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN" -G --data-urlencode "query@/tmp/zend