DocumentationAPI Reference

Ticket and New Ticket sidebar

The app is displayed in the apps tray on the right side of the ticket page or the new ticket page in the agent interface. The new ticket sidebar is for tickets being created in the new ticket page before they are submitted. Once submitted, the ticket is displayed in the ticket sidebar, even when a ticket's status is New.

By default, apps in the sidebar are assumed to be responsive. The iframe for responsive apps automatically resizes to match the apps tray's width as it changes. When designing an app, it is a good idea to follow best practices regarding responsive design. Use a responsive CSS framework to auto-adjust the positioning of elements in your app so that they are always roughly where you would like them to be. Tailwind CSS is a good way to do this, but there are other frameworks such as Materialize that solve a similar problem.

Note: While recommended, sidebar apps aren't required to be responsive. If you want an app's iframe to stay fixed to the default width of 320px, set the manifest file's location.flexible property to false.

Example manifest

"location": {  "support": {    "ticket_sidebar": {      "url": "assets/iframe.html",      "flexible": false    }  }},
"location": {  "support": {    "new_ticket_sidebar": {      "url": "assets/iframe.html",      "flexible": false    }  }},

See Setting the app location.

In addition to the objects available in all locations, the following objects and actions are available in this location:

Events

In addition to the core events, the following events are available to an app in the ticket sidebar:

To add event listeners to your app, see Working with framework events.

Ticket change events

You can use the following events in a ticket sidebar app to listen for changes to the ticket:

  • ticket.assignee.group.id.changed
  • ticket.assignee.group.name.changed
  • ticket.assignee.user.email.changed
  • ticket.assignee.user.externalId.changed
  • ticket.assignee.user.id.changed
  • ticket.assignee.user.name.changed
  • ticket.brand.changed
  • ticket.collaborators.changed
  • ticket.comments.changed
  • ticket.conversation.changed
  • ticket.custom_field_[custom field ID].changed
  • ticket.customStatus.changed
  • ticket.due_date.changed
  • ticket.externalId.changed
  • ticket.form.id.changed
  • ticket.postSaveAction.changed
  • ticket.priority.changed
  • ticket.problem_id.changed
  • ticket.requester.email.changed
  • ticket.requester.externalId.changed
  • ticket.requester.id.changed
  • ticket.requester.name.changed
  • ticket.sharedWith.changed
  • ticket.status.changed
  • ticket.statusCategory.changed
  • ticket.subject.changed
  • ticket.tags.changed
  • ticket.type.changed

The events fire when the respective properties on the ticket change due to user interaction. The events can also fire when other apps make changes to the ticket.

Remember that change events relate specifically to the properties being listened to. For example, the ticket.form.id.changed event fires when the ticket form is changed. It doesn't mean that the form is fully loaded and ready to be manipulated. In these cases, you may want to use the _.defer underscore helper.

Channel change event

You can listen to the following event to track whenever the channel of the last transacted message between an end user and an agent in the ticket has changed:

  • channel.changed

Ticket field change events

You can use the ticketFields.[ticket field].optionValues.changed event in a ticket sidebar app to listen for changes to the availability of ticket field values.

Ticket fields supported:

  • assignee

Custom ticket field change events

You can use the ticket.custom_field_[custom field ID].changed event in a ticket sidebar app to listen for changes to custom ticket fields. Example:

client.on('ticket.custom_field_123123.changed', function(e) {  handleChange();});

In the example, 123123 is the ID of the custom field you want to listen to.

Ticket comment change events

You can use the following events in a ticket sidebar app to listen for changes to the current comment:

  • comment.text.changed
  • comment.type.changed
  • comment.attachments.changed

The comment.text.changed event fires on a new ticket when the Description field is changed.

Wildcard change events

In addition to the specific .changed events for ticket, user, and organization sidebar apps, you can also listen for a wildcard change event that fires for any of these change events.

Use the following syntax to define a wildcard event:

client.on('*.changed', function(e) {  handleChange();});

The handler for a wildcard event receives an event object as the first argument. In the case of the wildcard event, the object has two special properties to help you determine the underlying event that triggered the wildcard event:

PropertyMeaning
propertyNameThe underlying property that triggered the wildcard event
newValueThe value of the underlying property after the change

Example:

client.on('*.changed', function(e) {  var propertyName = e.propertyName;   // "ticket.assignee.user.email"  var newValue = e.newValue;           // "[email protected]"  handleChange(propertyName, newValue);});

Dynamic events can be useful for identifying and handling events that occur to fields that are installed using app requirements.

Ticket submission events

The following events correspond to the lifecycle of a ticket save action, which may be controlled by one or more ticket.save hook handlers. For more information, see Ticket save hook events.

EventDescription
ticket.submit.startThe ticket save has been initiated; hook handlers haven't run yet
ticket.submit.doneThe ticket save was successfully completed
ticket.submit.failThe ticket save failed due to a responding ticket.save hook handler
ticket.submit.alwaysThe ticket save lifecycle has been completed. Always fires regardless of success or failure

Example:

client.on('ticket.submit.start', function() {  // handler code});

The event handler doesn't receive any parameters.

Ticket updated events

You can use the following event to run some code when a ticket is updated by another agent:

  • ticket.updated

The event is useful for avoiding agent collisions, where one agent updates a ticket that another agent is currently working on. The event handler receives as a parameter the user who updated the ticket. See the User object.

The event fires when one of the following is true:

  • An end user updates a ticket.
  • Another agent saved changes to the ticket and the changes have been auto-updated to all other concurrent viewers.
  • The "Stay on ticket" behavior is in effect for an agent and the agent saves changes to the ticket.
  • An update is made to the ticket with the REST API.

Example:

client.on('ticket.updated', function(user) {  // Do something when the ticket is updated});

Ticket collision events

When another agent is viewing the same ticket as the logged-in agent, the following event fires:

  • ticket.viewers.changed

Listening for this event allows your app to display the other agents currently viewing the ticket.

The handler of the ticket.viewers.changed event receives an array of Collision User objects as the first argument. These objects, in addition to all the methods available for the User object, also have isEditing() and isIdle() methods to determine the viewer's state on the ticket.

Ticket save hook events

Hook events allow your app to hook into product events and block the completion of the event until your app responds.

You can use the following hook event in a ticket sidebar app:

  • ticket.save

The event fires immediately after a user clicks the ticket Submit As button, or presses a keyboard shortcut to save a ticket.

When a ticket.save hook fires, your app can run a custom function and decide whether the ticket save action should proceed or not. The hook handler can be synchronous or asynchronous.

Example:

client.on('ticket.save', function() {  // handler});

A ticket.save hook handler can affect the action that triggered it in one of two ways:

  • allow the ticket save action to proceed
  • prevent the ticket save action from proceeding
Allowing a ticket save action to proceed

To allow the ticket save action to proceed, return true. Example:

client.on('ticket.save', function() {  // do something  return true;});

If your app needs to do something asynchronous such as an AJAX request, use a promise.

If the promise is resolved, the save action proceeds.

Preventing a ticket save action from proceeding

To stop the ticket save action from proceeding in a general hook handler, return false. Example:

client.on('ticket.save', function() {  // do something  return false;});

You can notify the user that the action was cancelled. See "Notifying the user if the ticket is not saved" below.

If your app needs to do something asynchronous such as an AJAX request, use a promise.

To halt the ticket save operation in an asynchronous function, the promise must be rejected. Example:

client.on('ticket.save', async () => {  return Promise.reject(false);});
Notifying the user if the ticket is not saved

When a ticket.save hook handler cancels a ticket save action, you can display a custom message in a notification box on the upper-right side of the Zendesk Support interface.

image

The custom message is displayed as an error notification, meaning that it's styled as an error and is persistent in the agent interface until the user dismisses it.

You can supply the notification by returning the string from the hook handler:

client.on('ticket.save', function() {  // do something  return "The ticket wasn't saved!";});

You can also supply the notification string as an argument to the reject() method in a promise.

If you don't supply a notification message, then a default message is displayed, along with the name of the app that disallowed the ticket save. The name is the value of the 'name' property in your manifest file. Example:

{    "name": "Hook Line and Sinker",    "author": {        "name": "Jennifer Hansen"    },    ...}
Resolving conflicts when multiple apps respond to the hook

More than one app may respond to the ticket.save hook. For example, when a user tries to save a ticket, two apps may allow the action to proceed while a third app may not. If multiple apps respond to the ticket.save hook, the following rules apply:

  • If any app disallows the ticket save, then the save action is canceled
  • If all apps allow the ticket save action, then the save action is performed
Global timeout

Because hook handlers can be asynchronous, it's possible that a handler may never respond. If one or more hook handlers fail to respond after a global timeout period of 60 seconds, the ticket save action is canceled and the hook handlers are ignored.

Using ticket submission events

The framework provides a number of ticket submission events in addition to the ticket.save hook. See Ticket submission events.

Ticket object

ticket

get
client.get('ticket')
returns
{  "ticket": {    // Ticket object properties  }}

Properties

Actions

ticket.assignee

Assignee is a composition of user (an agent) and his or her group.

get
client.get('ticket.assignee')
set
// Assign to a user within a groupclient.set('ticket.assignee', { groupId: <groupId>, userId: <userId> })
// Assign to a group onlyclient.set('ticket.assignee', { groupId:  <groupId> })
returns
{  "ticket.assignee": {    "group": {      // Group object properties    }    "user": {      // User object properties    }  }}

See Group and User object properties.

Limitations
  • If the assignee field is disabled, a request to set the ticket assignee returns an error.
  • To set an assignee with the groupId and userId parameters, the user must be an agent or admin. The agent or admin must belong to the specified group. Otherwise, the request returns an error.
  • If you set an assignee with a groupId parameter but no userId parameter, the original user value will be set to null.
  • If you set the assignee to an online agent during a live chat in the Zendesk Agent Workspace, then the chat will be transferred to the newly assigned agent.

ticket.brand

The ticket brand.

get
client.get('ticket.brand')
set
client.set('ticket.brand', value)
// or
client.set('ticket.brand', { id: value })
returns
{  "ticket.brand": {    //Brand object properties  }}

See Brand object properties.

ticket.collaborators

The list of collaborators on the ticket. When CCs and followers permissions are enabled in Support, a list of CCs and followers is returned. See Configuring CC and follower permissions.

get
client.get('ticket.collaborators')
returns
{  "ticket.collaborators": [{    // User object properties  }]}

See User object properties.

invoke
client.invoke('ticket.collaborators.add', { email: value })
// or
client.invoke('ticket.collaborators.add', { id: value })
invoke
client.invoke('ticket.collaborators.remove', { email: value })
// or
client.invoke('ticket.collaborators.remove', { id: value })

ticket.comment

The currently editing comment.

get
client.get('ticket.comment')
returns
{  "ticket.comment": {    //Comment object properties  }}

See Comment object properties.

ticket.comments

An array of existing Comment Event objects from the ticket conversations and events. These objects are different from the Comment object.

Note: This property doesn't return comments from Web Widget (Classic), messaging or Event Log. To fetch these comments, use the ticket.conversation property.

get
client.get('ticket.comments')
returns
{  "ticket.comments": [{      // Comment Event object properties  }]}

Limits: 65k characters

ticket.conversation

A lightweight version of ticket.comments that returns ticket conversations and events, including messages from Web Widget (Classic) and messaging.

get
client.get('ticket.conversation')
returns
{  "ticket.conversation": [    {      "attachments": [{        "contentType": string,        "contentUrl": string,        "filename": string      }],      "author": {        "id": number | null,        "avatar": string,        "name": string,        "role": string      },      "channel": {        "name": string // Returns the channel that the message was sent from.      },      "message": {        "content": string | null,        "contentType": string | null      },      "timestamp": ISO 8601 formatted date time // YYYY-MM-DDTHH:MM:SSZ    }  ]}
Specifications
Supported channel names
Channel NameDescription
webPublic agent, admin, and end-user comments from the Zendesk Support email channel
internalPrivate agent and admin comments
voiceCall and voicemail recording comments from the Zendesk Talk channel
chatPublic agent, admin, and end-user messages from the Web Widget (Classic)
native_messagingPublic agent, admin, and end-user messages from Web and mobile messaging
linePublic agent, admin, and end-user messages from the LINE social messaging channel
wechatPublic agent, admin, and end-user messages from the WeChat social messaging channel
sunshine_conversations_twitter_dmPublic agent, admin, and end-user messages from the X (formerly Twitter) direct messages social messaging channel
sunshine_conversations_facebook_messengerPublic agent, admin, and end-user messages from the Facebook Messenger social messaging channel
instagram_dmPublic agent, admin, and end-user messages from the Instagram direct messages social messaging channel
whatsappPublic agent, admin, and end-user messages from the WhatsApp social messaging channel
any_channelPublic end-user messages from Channel integrations
twitterPublic and private (X direct messages) end-user messages from the legacy public X channel
facebookPublic and private (Facebook Messenger) end-user messages from the legacy public Facebook channel
apiPublic comments from the Support API
chat_transcriptIf Agent Workspace is enabled, the chat transcript message in ticket events from Web Widget (Classic) and messaging. If Agent Workspace is not enabled, the chat transcript comment in the ticket conversations from Web Widget (Classic).
Supported author roles
  • "system" (such as a Zendesk bot)
  • "trigger"
  • "agent"
  • "admin"
  • "end-user"
Supported message content types
Channel NameMessage Content Type
webtext/html
internaltext/html
voicenull (call and voicemail recordings are included as attachments)
chattext/plain
native_messagingtext/plain
linetext/plain
wechattext/plain
sunshine_conversations_twitter_dmtext/plain
sunshine_conversations_facebook_messengertext/plain
instagram_dmtext/plain
whatsapptext/plain
any_channeltext/html
twittertext/html
facebooktext/html
apitext/html
chat_transcripttext/html
Limitations
  • The author id is null when the author has a "system" or "trigger" role.

ticket.customField:fieldName

The ticket custom field value as its defined type. Specify fieldName as custom_field_<custom field ID>.

get
client.get('ticket.customField:fieldName') // For example, client.get('ticket.customField:custom_field_1234')
set
client.set('ticket.customField:fieldName', value) // For example, client.set('ticket.customField:custom_field_1234', value)
returns
{  "ticket.customField:fieldName": string}

Limits:

  • Single-line custom field: 53 characters
  • Multi-line custom field: 63k characters
  • Numeric custom field: 12 characters
  • Decimal custom field: 65k characters

ticket.customStatus

The ticket custom status. This property is only available if custom ticket statuses are enabled. See Enabling Ticket Statuses.

Note: Setting a custom ticket status triggers a ticket.customStatus.changed event. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers a ticket.statusCategory.changed event.

get
client.get('ticket.customStatus')
returns
{  "ticket.customStatus": {    "id": number    "name": string // Name (agent view)  }}
set

The value is a valid ticket custom status id. If the id is invalid, the setter returns the following error:

> Could not find custom status with id 671172

Note:: You can fetch a list of custom ticket statuses using a client.get(ticketFields:status) call or the /api/v2/custom_statuses.json endpoint.

client.set('ticket.customStatus', { id: value })
returns
{  "ticket.customStatus": {    "id": number    "name": string // Name (agent view)  }}

ticket.createdAt

When the ticket was created using the ISO 8601 format.

get
client.get('ticket.createdAt')
returns
{  "ticket.createdAt": ISO 8601 formatted date time}

ticket.description

The ticket description.

get
client.get('ticket.description')
returns
{  "ticket.description": string}

ticket.editor

The ticket editor. See Ticket Editor object.

ticket.externalId

The ticket external ID

get
client.get('ticket.externalId')
set
client.set('ticket.externalId', value)
returns
{  "ticket.externalId": string}

ticket.form

The current ticket form.

get
client.get('ticket.form')
returns
{  "ticket.form": {    Ticket Form object properties  }}

See Ticket Form object properties.

ticket.id

The ticket ID.

get
client.get('ticket.id')
returns
{  "ticket.id": integer}

ticket.isNew

Is the ticket new?

get
client.get('ticket.isNew')
returns
{  "ticket.isNew": boolean}

ticket.organization

The ticket organization.

get
client.get('ticket.organization')
returns
{  "ticket.organization": {    //Organization properties  }}

See Organization object for the properties.

ticket.postSaveAction

What happens next when a ticket is saved. Possible values: "Next available ticket" (in Guided mode only), "Stay on ticket", "Next ticket in view", "Close tab"

get
client.get('ticket.postSaveAction')
returns
{  "ticket.postSaveAction": string}

ticket.priority

The ticket priority.

get
client.get('ticket.priority')
set

You can pass in one of the following values: low, normal, high, or urgent.

client.set('ticket.priority', value)
returns
{  "ticket.priority": string}

ticket.recipient

get
client.get('ticket.recipient')
set

Specify the user's email address to set the ticket recipient.

client.set('ticket.recipient', value)
returns
{  "ticket.recipient": string}

ticket.requester

The ticket requester.

get
client.get('ticket.requester')
set
client.set('ticket.requester', { email: value1, name: value2 }) // `name` is optional
// or
client.set('ticket.requester', { id: value })
returns
{  "ticket.requester": {    //User object properties  }}

See User object properties.

ticket.sendMessage

Sends a message to the end-user, on behalf of the agent. Only works during live chat (channel = chat) and messaging (channel = messaging) conversations for the time being.

invoke
client.invoke('ticket.sendMessage', { channel: value1, message: value2 })// Example: client.invoke('ticket.sendMessage', { channel: 'chat', message: 'Hello, world.' })// Example: client.invoke('ticket.sendMessage', { channel: 'messaging', message: 'Hello, world.' })

ticket.sharedWith

The ticket shared agreement.

get
client.get('ticket.sharedWith')
set
client.set('ticket.sharedWith', { id: value })
returns
{  "ticket.sharedWith": [{    //Sharing agreement object properties  }]}

See Sharing agreement object properties.

ticket.status

The ticket status.

get
client.get('ticket.status')
set

For a new ticket, you can pass in one of the following values: "new", "open", "pending", "hold", and "solved".

For an existing ticket, you can pass in one of the following values: "open", "pending", "hold", and "solved".

Note: Setting a custom ticket status triggers a ticket.customStatus.changed event. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers a ticket.statusCategory.changed event.

client.set('ticket.status', value)
returns
{  "ticket.status": string}

ticket.statusCategory

The ticket status category.

Note: Setting a custom ticket status triggers a ticket.customStatus.changed event. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers a ticket.statusCategory.changed event.

get
client.get('ticket.statusCategory')
set

For a new ticket, you can pass in one of the following values: "new", "open", "pending", "hold", or "solved".

For an existing ticket, you can pass in one of the following values: "open", "pending", "hold", or "solved".

client.set('ticket.statusCategory', value)
returns
{  "ticket.statusCategory": string}

ticket.subject

The ticket subject.

get
client.get('ticket.subject')
set
client.set('ticket.subject', value)

Limits: 255 characters

returns
{  "ticket.subject": string}

ticket.tags

The list of tags on the ticket.

get
client.get('ticket.tags')
set
client.set('ticket.tags', [values])

argument

  • values an array of tags (strings)
returns
{  "ticket.tags": [    //string  ]}

Limits: 5096 characters, for all tags in aggregate

invoke
client.invoke('ticket.tags.add', value)
// or
client.invoke('ticket.tags.add', [value1, value2])
invoke
client.invoke('ticket.tags.remove', value)
// or
client.invoke('ticket.tags.remove', [value1, value2])

ticket.type

The ticket type.

get

Returns one of the following values: question, incident, problem, or task.

client.get('ticket.type')

If the type is task, you can retrieve the task's due date, if any, with the ticket.customField:fieldName API. Specify 'due_date' as the fieldName parameter.

client.get('ticket.type').then(function(data) {  if (data['ticket.type'] === 'task') {    client.get('ticket.customField:due_date').then(function(data) {      var taskDue = data['ticket.customField:due_date'];    });  }});

If the type is incident, you can retrieve the ID of the linked problem ticket, if any, with the ticket.customField:fieldName API. Specify 'problem_id' as the fieldName parameter.

client.get('ticket.type').then(function(data) {  if (data['ticket.type'] === 'incident') {    client.get('ticket.customField:problem_id').then(function(data) {      var problemId = data['ticket.customField:problem_id'];    });  }});
set

You can pass in one of the following values: question, incident, problem, or task.

client.set('ticket.type', value)

If you set the type to task, you can set the task's due date with the ticket.customField:fieldName API. Specify 'due_date' as the fieldName parameter.

client.set({  'ticket.type': 'task',  'ticket.customField:due_date': '2020/02/30'});
returns
{  "ticket.type": string}

If you set the type to incident, you can set the ID of the linked problem ticket with the ticket.customField:fieldName API. Specify 'problem_id' as the fieldName parameter.

client.set({  'ticket.type': 'incident',  'ticket.customField:problem_id': 78});

ticket.updatedAt

When the ticket was last updated.

get
client.get('updatedAt')
returns
{  "ticket.updatedAt": ISO 8601 formatted date time}

ticket.via

Channel used to create the ticket, such as email, API, or web. The channel is represented as a Via object.

get
client.get('ticket.via')
returns
{  "ticket.via": {    //Via object properties  }}

See Via object properties.

ticket.viewers

Other agents viewing the current ticket.

get
client.get('ticket.viewers')
returns
{  "ticket.viewers": [{    //Collision User object properties  }]}

See Collision User object properties.

disableSave

invoke
client.invoke('disableSave')

enableSave

invoke
client.invoke('enableSave')

Channel object

This object contains details of the channel based on the last transacted message between an end user and an agent. Agent-to-agent conversations, such as internal notes, are ignored.

channel

get
client.get('channel')
returns
{  "ticket": {    // Channel object properties  }}

Properties

channel.name

get
client.get('channel.name')
returns
{  "channel.name": string // email, chat, web, facebook, whatsapp, etc..}

This property should only be used for reporting and analytics purposes.

channel.sessionBased

Specifies if the channel is asynchronous or synchronous. This property could be used to drive agent experience functionality in a Zendesk Support app depending on the immediacy of the channel that the agent is using.

Session-based messaging is defined as communication channels that involve real-time conversations between two parties who are simultaneously participating. Example of session-based messaging include Zendesk Chat and Zendesk Talk conversations. Non-session-based messaging refers to channels featuring conversations that can occur in real-time but are usually asynchronous. Examples include email, social messaging, or web form ticketing.

get
client.get('channel.sessionBased')
returns
{  "channel.sessionBased": boolean}

channel.sessionActive

If the current channel of the editor is synchronous, then this property specifies if the channel is currently in a live session or not.

get
client.get('channel.sessionActive')
returns
{  "channel.sessionActive": boolean}

Comment object

comment

get
client.get('comment')
returns
{  "comment": {    // Comment object properties  }}

Properties

Actions

comment.attachments

get
client.get('comment.attachments')
returns
{  "comment.attachments": [{    // Comment Attachment object properties  }]}

See Comment Attachment object properties.

comment.text

get
client.get('comment.text')
set
client.set('comment.text', value)
returns
{  "comment.text": string}

In the Zendesk Agent Workspace, setting comment.text during a chat conversation auto-transpiles rich text into plain text (Markdown syntax) in the chat editor.

comment.type

Note: In the Zendesk Agent Workspace, comment.type is only partially supported. We recommend using ticket.editor.targetChannel instead.

get

Returns facebookPrivateMessage, facebookWallReply, internalNote, publicReply, twitterDirectMessage, or twitterReply.

client.get('comment.type')
set

You can pass in one of the following values: facebookPrivateMessage, facebookWallReply, internalNote, publicReply, twitterDirectMessage, twitterReply.

client.set('comment.type', value)
returns
{  "comment.type": string}

comment.useRichText

get
client.get('comment.useRichText')
returns
{  "comment.useRichText": boolean}

comment.appendHtml

Note: When using comment.appendHtml, HTML comments goes through a HTML sanitizer and normalizer for security reasons and to match the HTML rules for the ticket editor. This involves removing most CSS and some HTML tags which affects table formatting.

invoke
client.invoke('comment.appendHtml', value)
returns
{  "errors": {}}

comment.appendMarkdown

invoke
client.invoke('comment.appendMarkdown', value)
returns
{  "errors": {}}

comment.appendText

invoke
client.invoke('comment.appendText', value)
returns
{  "errors": {}}

Comment Attachment object

The Comment Attachment object represents ticket comment attachments. It has the following properties:

Properties

Note: The headings use a placeholder named "attachment" to refer to the attachment object. This is not an actual object name.

attachment.contentType

get
client.get('comment.attachments.0.contentType')
returns
{  "comment.attachments.0.contentType": string}

attachment.contentUrl

get
client.get('comment.attachments.0.contentUrl')
returns
{  "comment.attachments.0.contentUrl": string}

attachment.filename

get
client.get('comment.attachments.0.filename')
returns
{  "comment.attachments.0.filename": string}

attachment.thumbnailUrl

Only available when the attachment is an image.

get
client.get('comment.attachments.0.thumbnailUrl')
returns
{  "comment.attachments.0.thumbnailUrl": string}

Comment Event object

Represents saved comments from the ticket's audits, including comment id, value, author, and attachments.

comments

get
client.get('ticket.comments')
returns
{  "ticket.comments": [    {      "id": 1,      "value": "Hi support team, I washed my phone with warm, soapy water and now your app doesn't work!",      "author": {        // User object properties      },      "via": {        // via object properties      },      "imageAttachments": [{        // Comment Attachment object properties      }],      "nonImageAttachments": [{        // Comment Attachment object properties      }]    }  ]}

See the User object and Comment Attachment object, as well as the via object REST API for more information on these fields.

Brand object

Properties

brand.hasHelpCenter

get
client.get('ticket.brand.hasHelpCenter')
returns
{  "ticket.brand.hasHelpCenter": boolean}

brand.id

get
client.get('brand.id')
returns
{  "ticket.brand.id": integer}

brand.isActive

get
client.get('ticket.brand.isActive')
returns
{  "ticket.brand.isActive": boolean}

brand.isDefault

get
client.get('ticket.brand.isDefault')
returns
{  "ticket.brand.isDefault": boolean}
get
client.get('ticket.brand.logo')
returns
{  "ticket.brand.logo": {    "contentType": string,    "contentUrl": string,    "filename": string  }}

brand.name

get
client.get('ticket.brand.name')
returns
{  "ticket.brand.name": string}

brand.subdomain

get
client.get('ticket.brand.subdomain')
returns
{  "ticket.brand.subdomain": string}

brand.url

get
client.get('ticket.brand.url')
returns
{  "ticket.brand.url": string}

Collision User object

The following properties are in addition to the methods provided by the regular User object.

Properties

user.isEditing

get
client.get('ticket.viewers.0.isEditing')
returns
{  "ticket.viewers.0.isEditing": boolean}

user.isIdle

client.get('ticket.viewers.0.isIdle')
returns
{  "ticket.viewers.0.isIdle": boolean}

Sharing Agreement object

A sharing agreement specifies the terms under which ticket sharing can occur and how shared tickets are managed. See Sharing tickets with other Zendesk Support accounts in Zendesk help, and Sharing Agreements in the API reference.

Properties

agreement.id

get
client.get('ticket.sharedWith.0.id')
returns
{  "ticket.sharedWith.0.id": integer}

agreement.name

get
client.get('ticket.sharedWith.0.name')
returns
{  "ticket.sharedWith.0.name": string}

agreement.partnerName

The partner name may be null.

get
client.get('ticket.sharedWith.0.partnerName')
returns
{  "ticket.sharedWith.0.partnerName": string}

Ticket Field object

ticketFields

Returns either the named ticket field, or all available ticket fields if you don't specify a name.

Available ticket field names:

  • brand
  • requester
  • assignee
  • collaborator
  • ticket_form_id (Enterprise only)
  • tags
  • type
  • priority
  • sharedWith (if a ticket sharing agreement is enabled)
  • due_date
  • organization (if the requester is associated with multiple organizations)
  • problem
  • status
  • custom_field_{id}

For custom fields, replace {id} with the custom field's ID. Example: custom_field_1234.

get all fields
client.get('ticketFields')
returns
{  "ticketFields": [    {    // Ticket field object properties    },    ...  ]}
get field by name
client.get('ticketFields:fieldName') // For example, client.get('ticketFields:custom_field_1234')
returns
{  "ticketFields:fieldName": {    // Ticket field object properties  }}

You can also access individual fields by their zero-indexed order.

get field by index
client.get('ticketFields.0')

You must use a period instead of a colon to specify the index.

returns
{  "ticketFields.0": {    // Ticket field object properties  }}

A ticket field object has the following properties and actions:

Properties

Actions

Note: The headings use a placeholder named "ticketField" to refer to the ticket field object. This is not an actual object name.

The examples refer to the ticket field object as ticketFields:identifier, where "identifier" is a placeholder for the field name or index number. If the identifier is an index number, the separator is a period instead of a colon. Example: `ticketFields.0`.

Note: You can't use ticketField actions on custom ticket statuses in the ticketFields:status.options or ticketFields:status.optionValues properties.

ticketField.name

get
client.get('ticketFields:identifier.name')
returns
{  "ticketFields:identifier.name": string}

ticketField.label

get
client.get('ticketFields:identifier.label')
set
client.set('ticketFields:identifier.label', value)
returns
{  "ticketFields:identifier.label": string}

ticketField.optionValues

If a value is specified, returns the specified option object. If no value is specified, returns all the available option objects. Only available for dropdown fields. This API only returns values that are selectable, not the ones that expand to a group of other options - the inverse of optionGroups.

get
client.get('ticketFields:identifier.optionValues')  // client.get('ticketFields:priority.optionValues')
returns
{  "ticketFields:identifier.optionValues": [{    // Ticket Field Option object properties  }]}

or

get
client.get('ticketFields:identifier.optionValues:value')  // client.get('ticketFields:priority.optionValues:urgent')
returns
{  "ticketFields:identifier.optionValues:value": {    // Ticket Field Option object properties  }}

You can also access individual options by their zero-indexed order:

get
client.get('ticketFields:identifier.optionValues.0')  // client.get('ticketFields:priority.optionValues.0')
returns
{  "ticketFields:identifier.optionValues.0": {    // Ticket Field Option object properties  }}

See Ticket Field Option object properties.

ticketField.optionGroups

If a value is specified, returns the specified option group object. If no value is specified, returns all the available option group objects. Only available for dropdown fields. This API only returns values that are expandable to a group of other options - the inverse of optionValues.

get
client.get('ticketFields:identifier.optionGroups')  // client.get('ticketFields:priority.optionGroups')
returns
{  "ticketFields:identifier.optionGroups": [{    // Ticket Field Option object properties  }]}

or

get
client.get('ticketFields:identifier.optionGroups:value')  // client.get('ticketFields:assignee.optionGroups:10007')
client.get('ticketFields:identifier.optionGroups:value')  // client.get('ticketFields:assignee.optionGroups:10007')
returns
{  "ticketFields:identifier.optionGroups:value": {    // Ticket Field Option object properties  }}

You can also access individual options by their zero-indexed order:

get
client.get('ticketFields:identifier.optionGroups.0')  // client.get('ticketFields:assignee.optionGroups.0')
returns
{  "ticketFields:identifier.optionGroups.0": {    // Ticket Field Option object properties  }}

See Ticket Field Option object properties.

ticketField.isRequired

get
client.get('ticketFields:identifier.isRequired') // example, client.get('ticketFields:assignee.isRequired')
returns
{  "ticketFields:identifier.isRequired": boolean}

ticketField.requiredOnStatuses

An array of possible ticket statuses. The ticket field is required when the ticket status is any of the listed statuses. Possible values: "new", "hold", "pending", "solved", and "open". Only the following fields listed here can have conditional requirements.

get
client.get('ticketFields:identifier.requiredOnStatuses') // example, client.get('ticketFields:type.requiredOnStatuses')
returns
{  "ticketFields:identifier.requiredOnStatuses": [    //status strings  ]}

ticketField.isVisible

get
client.get('ticketFields:identifier.isVisible' // example, client.get('ticketFields:assignee.isVisible')
returns
{  "ticketFields:identifier.isVisible": boolean}

ticketField.isEnabled

get
client.get('ticketFields:identifier.isEnabled') // example, client.get('ticketFields:assignee.isEnabled')
returns
{  "ticketFields:identifier.isEnabled": boolean}

ticketField.type

get
client.get('ticketFields:identifier.type') // example, client.get('ticketFields:assignee.type')
returns

Returns the type of the ticket field. For custom fields, this is one of "checkbox", "date", "decimal", "integer", "regexp", "tagger", "text", or "textarea". For built-in fields, this is "built-in".

{  "ticketFields:identifier.type": string}

status.optionValues.{index}.label

The label text for a ticket status.

get
client.get('ticketFields:status.optionValues.{index}.label')// For example, client.get('ticketFields:status.optionValues.0.label')
set
client.set('ticketFields:status.optionValues.{index}.label', 'string')// For example, client.set('ticketFields:status.optionValues.0.label', 'Submit as Open')
returns
{  "ticketFields:status.optionValues.{index}.label": "string"}

Limitations:

  • You can only set the label text for the "new", "open", "pending", "hold", and "solved" ticket status categories.

status.optionValues:{identifier}.label

The label text for a ticket status.

get
client.get('ticketFields:status.optionValues:{identifier}.label')// For example, client.get('ticketFields:status.optionValues:open.label')
set
client.set('ticketFields:status.optionValues:{identifier}.label', 'string')// For example, client.set('ticketFields:status.optionValues:open.label', 'Submit as Open')
returns
{  "ticketFields:status.optionValues:{identifier}.label": "string"}

Limitations:

  • You can only set the label text for the "new", "open", "pending", "hold", and "solved" ticket status categories.

ticketField.disable

invoke
client.invoke('ticketFields:identifier.disable')

ticketField.enable

invoke
client.invoke('ticketFields:identifier.enable')

ticketField.hide

invoke
client.invoke('ticketFields:identifier.hide')

ticketField.show

invoke
client.invoke('ticketFields:identifier.show')

ticketField.toggle

Toggling / alternating the field to be shown or hidden.

invoke
client.invoke('ticketFields:identifier.toggle')

Ticket Field Option object

The ticket field option object has the following properties and actions:

Properties

Actions

Note: The headings use a placeholder named "ticketFieldOption" to refer to the ticket field option object. This is not an actual object name.

The examples refer to the ticket field object as ticketFields:identifier, where "identifier" is a placeholder for the field name or index number. If the identifier is an index number, the separator is a period instead of a colon. Example: `ticketFields.0`.

ticketFieldOption.isEnabled

get
client.get('ticketFields:identifier.optionValues.0.isEnabled')
returns
{  "ticketFields:identifier.optionValues.0.isEnabled": boolean}

ticketFieldOption.isVisible

get
client.get('ticketFields:identifier.optionValues.0.isVisible')
returns
{  "ticketFields:identifier.optionValues.0.isVisible": boolean}

ticketFieldOption.label

get
client.get('ticketFields:identifier.optionValues.0.label')
set
client.set('ticketFields:identifier.optionValues.0.label', value)
returns
{  "ticketFields:identifier.optionValues.0.label": string}

ticketFieldOption.value

get
client.get('ticketFields:identifier.optionValues.0.value')
returns
{  "ticketFields:identifier.optionValues.0.value": string}

ticketFieldOption.disable

invoke
client.invoke('ticketFields:identifier.optionValues.0.disable')

ticketFieldOption.enable

invoke
client.invoke('ticketFields:identifier.optionValues.0.enable')

ticketFieldOption.hide

invoke
client.invoke('ticketFields:identifier.optionValues.0.hide')

ticketFieldOption.show

invoke
client.invoke('ticketFields:identifier.optionValues.0.show')

ticketFieldOption.toggle

invoke
client.invoke('ticketFields:identifier.optionValues.0.toggle')

Ticket Form object

Properties

form.id

get
client.get('ticket.form.id')
set
client.set('ticket.form', { id: value })
returns
{  "ticket.form": { id: integer }}

Alternatively,

set
client.set('ticket.form.id', value)
returns
{  "ticket.form.id": integer}

Macro Object

macros

Returns all available macros, or one, if an index is specified.

get all macros
client.get('macros')
returns
{  "macros": [    {    // Macro object properties    },    ...  ]}

You can access individual macros by their zero-indexed order.

get macro by index
client.get('macros.0')
returns
{  "macros.0": {    // Macro object properties  }}

A macro object has the following properties and actions:

Properties

Actions

macro.id

get
client.get('macros.0.id')
returns

Returns the id of the macro.

{  "macros.0.id": integer}

macro.availability_type

get
client.get('macros.0.availability_type')
returns

Returns the availability type of the macro, one of "everyone", "group", or "personal".

{  "macros.0.availability_type": string}

macro.description

get
client.get('macros.0.description')
returns

Returns the description of the macro.

{  "macros.0.description": string}

macro.title

get
client.get('macros.0.title')
returns

Returns the title of the macro.

{  "macros.0.title": string}

macro

Invoking a macro will have the same effect as if the user were to select the macro via the UI.

invoke
client.invoke('macro', 123)

Via object

Properties

via.channel

How the ticket was created. Examples: "web", "mobile", "api"

get
client.get('ticket.via.channel')
returns
{  "ticket.via.channel": string}

via.source

For some channels, an object that gives more information about how or why the ticket was created.

get
client.get('ticket.via.source')
returns
{  "ticket.via.source": // Source object properties}

For details, see Via Object in the REST API documentation.