Zendesk

Procedures and concepts for the Zendesk integration.

The following documentation is for Zendesk v3.3.0 (BDK).

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 Install or Add Connection to add the book to your agent.

4. If adding a connection, you'll be prompted for connectivity details.

Connectivity

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

This books supports the connectivity methods described in this section.In here you will find information about what information is required in order to employ each method.

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:

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	The ticket to which the comment will be added.	zendesk ticket	Yes	(no default)
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	The updated ZendeskTicket object with the new comment.	zendesk ticket

Examples

Add a simple comment

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

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	The ticket to be created in Zendesk, represented as a ZendeskTicket concept.	zendesk ticket	Yes	(no default)

Output Concepts

Concept	Description	Type
ticket	A zendesk concept representing the created ticket.	zendesk ticket

Examples

Create a Ticket

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	The ticket concept to delete.	zendesk ticket	Yes	(no default)

Examples

Delete a ticket

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	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

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	A ZendeskTicket object representing the retrieved ticket.	zendesk ticket

Examples

Get a ticket

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	A ZendeskUser object representing the retrieved user.	zendesk user

Examples

Get a user

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	The ticket to get audits for.	zendesk ticket	Yes	(no default)

Output Concepts

Concept	Description	Type
ticket's audits	A list of ZendeskAudit objects representing the audit trail.	zendesk audit

Examples

Get audits for a ticket

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	The ticket to get comments for.	zendesk ticket	Yes	(no default)

Output Concepts

Concept	Description	Type
ticket's comments	A list of ZendeskComment objects representing the retrieved comments.	zendesk comment

Examples

Get comments for a ticket

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

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	A list of ZendeskUser objects representing the retrieved users.	zendesk user

Examples

Get all users

get some users in zendesk

Get users with filter expression

get some users in zendesk whose role is "agent"

Get users with pagination

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	A list of Zendesk Ticket fields representing all available fields and custom fields.	zendesk ticket field

Examples

Get all ticket fields

get ticket fields in zendesk

to search some (tickets) in zendesk

FILTER - CAPABLE

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	A list of ZendeskTicket objects representing the retrieved tickets.	zendesk ticket

Examples

Get some tickets

search some tickets in zendesk

Get tickets with filter expression

search some tickets in zendesk whose status is "open"

Get tickets with pagination

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	The ticket to be updated in Zendesk, represented as a ZendeskTicket object.	zendesk ticket	Yes	(no default)

Output Concepts

Concept	Description	Type
ticket	The updated ticket information as returned by Zendesk.	zendesk ticket

Examples

Update a ticket's status and priority

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	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	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	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	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?]