# Zendesk

{% hint style="info" %}
The following documentation is for **Zendesk v3.3.0** *(BDK)*.
{% endhint %}

## Overview

Zendesk is a customer service platform providing ticketing, knowledge base, and customer support management. This integration enables automated ticket creation, customer communication, support workflow management, and help desk automation. Improve customer service efficiency and support team productivity.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Zendesk**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using subdomain, email and token

Connects to Zendesk using email and API token authentication.

| Label     | Description                                     | Type   |
| --------- | ----------------------------------------------- | ------ |
| subdomain | The subdomain of your Zendesk account.          | `text` |
| email     | The email associated with your Zendesk account. | `text` |
| token     | The API token from Zendesk for authentication.  | `text` |

### Configuration

The following table details all the available configuration options for this book.

| Concept   | Description                                          | Type     | Default Value |
| --------- | ---------------------------------------------------- | -------- | ------------- |
| `timeout` | Timeout in seconds when making API calls to Zendesk. | `number` | 30000         |

Configuration can be set or retrieved as shown in the following examples:

```generic
the department's Zendesk's timeout is 30000
```

## Procedures

### to add a comment to a (ticket)

Adds a comment to an existing ticket in Zendesk with an optional single file attachment.

Note: If the attachment is specified, it must include the attachment\_name with extension.

**Input Concepts**

| Concept                       | Description                                    | Type              | Required | Default Value |
| ----------------------------- | ---------------------------------------------- | ----------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket)   | The ticket to which the comment will be added. | `zendesk ticket`  | Yes      | (no default)  |
| [`comment`](#zendesk-comment) | The comment to add to the ticket.              | `zendesk comment` | Yes      | (no default)  |
| `attachment`                  | The file to attach to the comment.             | `file`            | No       | (no default)  |
| `attachment name`             | The name of the attachment.                    | `text`            | No       | (no default)  |

**Output Concepts**

| Concept                     | Description                                            | Type             |
| --------------------------- | ------------------------------------------------------ | ---------------- |
| [`ticket`](#zendesk-ticket) | The updated ZendeskTicket object with the new comment. | `zendesk ticket` |

**Examples**

Add a simple comment

```generic
the ticket # Assume we already have a ticket concept in the KLang
create a json
use the above as the comment
the comment's body is "This is a test comment"
add the comment to the ticket
```

Add a comment with an attachment

```generic
the ticket # Assume we already have a ticket concept in the KLang
the attachment # Assume we already have an attachment in the KLang
create a json
use the above as the comment
the comment's body is "This is a test comment"
add the comment to the ticket
    the attachment is the attachment
    the attachment name is "test.pdf"
```

### to create a (ticket) in *zendesk*

Creates a new ticket in Zendesk with the specified properties.

**Input Concepts**

| Concept                     | Description                                                                  | Type             | Required | Default Value |
| --------------------------- | ---------------------------------------------------------------------------- | ---------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket) | The ticket to be created in Zendesk, represented as a ZendeskTicket concept. | `zendesk ticket` | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                                        | Type             |
| --------------------------- | -------------------------------------------------- | ---------------- |
| [`ticket`](#zendesk-ticket) | A zendesk concept representing the created ticket. | `zendesk ticket` |

**Examples**

Create a Ticket

```generic
create a json
use the above as the ticket
the ticket's subject is "Test"
the ticket's description is "This is a test ticket"
create the ticket in zendesk
```

### to delete a ticket in *zendesk*

Deletes a specified ticket in Zendesk.

**Input Concepts**

| Concept                     | Description                   | Type             | Required | Default Value |
| --------------------------- | ----------------------------- | ---------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket) | The ticket concept to delete. | `zendesk ticket` | Yes      | (no default)  |

**Examples**

Delete a ticket

```generic
get some tickets in zendesk
use the first ticket as the ticket
delete the ticket in zendesk
```

### to download an (attachment)

Downloads an attachment from Zendesk.

**Input Concepts**

| Concept                             | Description                        | Type                 | Required | Default Value |
| ----------------------------------- | ---------------------------------- | -------------------- | -------- | ------------- |
| [`attachment`](#zendesk-attachment) | The ZendeskAttachment to download. | `zendesk attachment` | Yes      | (no default)  |

**Output Concepts**

| Concept      | Description                                                     | Type   |
| ------------ | --------------------------------------------------------------- | ------ |
| `attachment` | A file-like object (BytesIO) containing the attachment content. | `file` |

**Examples**

Download an attachment from a comment

```generic
the ticket # Assume we already have a ticket
get the ticket's comments in zendesk
use the first comment as the comment
use the comment's first attachment as the attachment
download the attachment
```

### to get a (ticket) in *zendesk*

Retrieves a specific ticket from Zendesk by its ID using direct API access.

This method uses the direct ticket API (not search) so it works immediately after ticket creation without waiting for search index updates.

**Input Concepts**

| Concept     | Description                       | Type     | Required | Default Value |
| ----------- | --------------------------------- | -------- | -------- | ------------- |
| `ticket id` | The ID of the ticket to retrieve. | `number` | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                                               | Type             |
| --------------------------- | --------------------------------------------------------- | ---------------- |
| [`ticket`](#zendesk-ticket) | A ZendeskTicket object representing the retrieved ticket. | `zendesk ticket` |

**Examples**

Get a ticket

```generic
get a ticket in zendesk
    the ticket id is 12345
```

### to get a (user) in *zendesk*

Retrieves a specific user from Zendesk by their ID.

**Input Concepts**

| Concept   | Description                     | Type     | Required | Default Value |
| --------- | ------------------------------- | -------- | -------- | ------------- |
| `user id` | The ID of the user to retrieve. | `number` | Yes      | (no default)  |

**Output Concepts**

| Concept                 | Description                                           | Type           |
| ----------------------- | ----------------------------------------------------- | -------------- |
| [`user`](#zendesk-user) | A ZendeskUser object representing the retrieved user. | `zendesk user` |

**Examples**

Get a user

```generic
get a user in zendesk
    the user id is 12345
```

### to get some (ticket's audits) in *zendesk*

Retrieves all audits for a specific ticket in Zendesk.

**Input Concepts**

| Concept                     | Description                   | Type             | Required | Default Value |
| --------------------------- | ----------------------------- | ---------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket) | The ticket to get audits for. | `zendesk ticket` | Yes      | (no default)  |

**Output Concepts**

| Concept                             | Description                                                  | Type            |
| ----------------------------------- | ------------------------------------------------------------ | --------------- |
| [`ticket's audits`](#zendesk-audit) | A list of ZendeskAudit objects representing the audit trail. | `zendesk audit` |

**Examples**

Get audits for a ticket

```generic
the ticket # Assume we already have a ticket concept
get the ticket's audits in zendesk
```

### to get some (ticket's comments) in *zendesk*

Retrieves all comments for a specific ticket in Zendesk.

**Input Concepts**

| Concept                     | Description                     | Type             | Required | Default Value |
| --------------------------- | ------------------------------- | ---------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket) | The ticket to get comments for. | `zendesk ticket` | Yes      | (no default)  |

**Output Concepts**

| Concept                                 | Description                                                           | Type              |
| --------------------------------------- | --------------------------------------------------------------------- | ----------------- |
| [`ticket's comments`](#zendesk-comment) | A list of ZendeskComment objects representing the retrieved comments. | `zendesk comment` |

**Examples**

Get comments for a ticket

```generic
the ticket # Assume we already have a ticket concept in the KLang
get the ticket's comments in zendesk
```

### to get some (users) in *zendesk*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves users from Zendesk using search functionality with optional filter expressions.

**Input Concepts**

| Concept  | Description                                             | Type     | Required | Default Value |
| -------- | ------------------------------------------------------- | -------- | -------- | ------------- |
| `offset` | Number of results to skip for pagination. Default is 0. | `number` | No       | (no default)  |
| `limit`  | Maximum number of users to return. Default is 10.       | `number` | No       | (no default)  |

**Output Concepts**

| Concept                  | Description                                                     | Type           |
| ------------------------ | --------------------------------------------------------------- | -------------- |
| [`users`](#zendesk-user) | A list of ZendeskUser objects representing the retrieved users. | `zendesk user` |

**Examples**

Get all users

```generic
get some users in zendesk
```

Get users with filter expression

```generic
get some users in zendesk whose role is "agent"
```

Get users with pagination

```generic
get some users in zendesk
    the offset is 0
    the limit is 10
```

### to get ticket fields in *zendesk*

Retrieves all available ticket field definitions from Zendesk.

This method can be used to resolve the fields and custom fields information.

**Output Concepts**

| Concept                           | Description                                                                          | Type                   |
| --------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- |
| [`answer`](#zendesk-ticket-field) | A list of Zendesk Ticket fields representing all available fields and custom fields. | `zendesk ticket field` |

**Examples**

Get all ticket fields

```generic
get ticket fields in zendesk
```

### to search some (tickets) in *zendesk*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Retrieves tickets from Zendesk using search functionality with optional filter expressions.

NOTE: This method uses the search API, which might not return immediately updated data after ticket creation. It may take up to some minutes to index newly created tickets. If you need immediate access to the ticket data, use the get\_ticket\_by\_id method instead. If you want the custom fields names and values use the get\_ticket\_fields method

**Input Concepts**

| Concept  | Description                               | Type     | Required | Default Value |
| -------- | ----------------------------------------- | -------- | -------- | ------------- |
| `offset` | Number of results to skip for pagination. | `number` | No       | (no default)  |
| `limit`  | Maximum number of tickets to return.      | `number` | No       | (no default)  |

**Output Concepts**

| Concept                      | Description                                                         | Type             |
| ---------------------------- | ------------------------------------------------------------------- | ---------------- |
| [`tickets`](#zendesk-ticket) | A list of ZendeskTicket objects representing the retrieved tickets. | `zendesk ticket` |

**Examples**

Get some tickets

```generic
search some tickets in zendesk
```

Get tickets with filter expression

```generic
search some tickets in zendesk whose status is "open"
```

Get tickets with pagination

```generic
search some tickets in zendesk
    the offset is 0
    the limit is 10
```

### to update a (ticket) in *zendesk*

Updates a specific ticket in Zendesk with the provided information.

**Input Concepts**

| Concept                     | Description                                                                 | Type             | Required | Default Value |
| --------------------------- | --------------------------------------------------------------------------- | ---------------- | -------- | ------------- |
| [`ticket`](#zendesk-ticket) | The ticket to be updated in Zendesk, represented as a ZendeskTicket object. | `zendesk ticket` | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                                            | Type             |
| --------------------------- | ------------------------------------------------------ | ---------------- |
| [`ticket`](#zendesk-ticket) | The updated ticket information as returned by Zendesk. | `zendesk ticket` |

**Examples**

Update a ticket's status and priority

```generic
the ticket # Assume we already have a ticket concept in the KLang
the ticket's status is "open"
the ticket's priority is "high"
update the ticket in zendesk
```

## Concepts

### Zendesk ticket

A ticket in Zendesk.

| Field Name                   | Description                                                       | Type                     |
| ---------------------------- | ----------------------------------------------------------------- | ------------------------ |
| `id`                         | The ID of the ticket.                                             | `optional[number]`       |
| [`assignee`](#zendesk-user)  | The assignee of the ticket.                                       | `optional[zendesk user]` |
| `created_at`                 | The creation date of the ticket.                                  | `optional[datetime]`     |
| `custom_fields`              | List of custom fields as dictionaries with 'id' and 'value' keys. | `optional[list of json]` |
| `description`                | The description of the ticket.                                    | `optional[text]`         |
| `due_at`                     | The due date of the ticket.                                       | `optional[datetime]`     |
| `priority`                   | The priority of the ticket.                                       | `optional[text]`         |
| `requester_id`               | The ID of the requester.                                          | `optional[number]`       |
| [`submitter`](#zendesk-user) | The submitter of the ticket.                                      | `optional[zendesk user]` |
| `status`                     | The status of the ticket.                                         | `optional[text]`         |
| `subject`                    | The subject of the ticket.                                        | `optional[text]`         |
| `tags`                       | The tags of the ticket.                                           | `optional[list of text]` |
| `type`                       | The type of the ticket.                                           | `optional[text]`         |
| `url`                        | The URL of the ticket.                                            | `optional[text]`         |

### Zendesk user

A user in Zendesk.

| Field Name | Description            | Type               |
| ---------- | ---------------------- | ------------------ |
| `id`       | The ID of the user.    | `optional[number]` |
| `email`    | The email of the user. | `optional[text]`   |
| `name`     | The name of the user.  | `optional[text]`   |

### Zendesk comment

A comment in Zendesk.

| Field Name                           | Description                                                       | Type                                   |
| ------------------------------------ | ----------------------------------------------------------------- | -------------------------------------- |
| `id`                                 | The ID of the comment.                                            | `optional[number]`                     |
| `body`                               | The content/text of the comment.                                  | `optional[text]`                       |
| [`author`](#zendesk-user)            | The user who created the comment.                                 | `optional[zendesk user]`               |
| `created_at`                         | When the comment was created.                                     | `optional[datetime]`                   |
| `public`                             | Whether the comment is public (true) or an internal note (false). | `optional[boolean]`                    |
| `type`                               | The type of comment (Comment, VoiceComment, etc.).                | `optional[text]`                       |
| [`attachments`](#zendesk-attachment) | List of ZendeskAttachment objects.                                | `optional[list of zendesk attachment]` |

### Zendesk attachment

An attachment in Zendesk.

| Field Name     | Description                                 | Type               |
| -------------- | ------------------------------------------- | ------------------ |
| `id`           | The ID of the attachment.                   | `optional[number]` |
| `file_name`    | The name of the file.                       | `optional[text]`   |
| `content_url`  | The URL to download the attachment content. | `optional[text]`   |
| `content_type` | The MIME type of the attachment.            | `optional[text]`   |
| `size`         | The size of the attachment in bytes.        | `optional[number]` |

### Zendesk audit

An audit record for a ticket in Zendesk.

| Field Name   | Description                                             | Type                             |
| ------------ | ------------------------------------------------------- | -------------------------------- |
| `id`         | The ID of the audit.                                    | `optional[number]`               |
| `ticket_id`  | The ID of the ticket this audit belongs to.             | `optional[number]`               |
| `created_at` | When the audit was created.                             | `optional[datetime]`             |
| `author_id`  | The ID of the user who performed the action.            | `optional[number]`               |
| `metadata`   | Additional metadata about the audit.                    | `optional[json]`                 |
| `events`     | List of events in this audit (changes, comments, etc.). | `optional[list of list of any?]` |

### Zendesk ticket field

A custom field definition for Zendesk tickets.

| Field Name    | Description                                                       | Type             |
| ------------- | ----------------------------------------------------------------- | ---------------- |
| `id`          | The ID of the ticket field.                                       | `number`         |
| `title`       | The human-readable title of the field.                            | `optional[text]` |
| `type`        | The type of the field (text, textarea, checkbox, dropdown, etc.). | `optional[text]` |
| `description` | The description of the field.                                     | `optional[text]` |
| `value`       | The actual value for this field on a specific ticket.             | `optional[any?]` |