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:

• Ticket object
• Channel object
• Comment object
• Comment Attachment object
• Comment Event object
• Brand object
• Collision User object
• Sharing Agreement object
• Ticket Field object
• Ticket Field Option object
• Ticket Form object
• Macro Object
• Via Object
• Ticket editor object
• Additional actions

Events

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

• Ticket change events
• Channel change event
• Ticket field change events
• Custom ticket field change events
• Ticket comment change events
• Wildcard change events
• Ticket submission events
• Ticket updated events
• Ticket collision events
• Ticket save hook events

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:

Property	Meaning
propertyName	The underlying property that triggered the wildcard event
newValue	The 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.

Event	Description
ticket.submit.start	The ticket save has been initiated; hook handlers haven't run yet
ticket.submit.done	The ticket save was successfully completed
ticket.submit.fail	The ticket save failed due to a responding ticket.save hook handler
ticket.submit.always	The 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.

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

• ticket.assignee
• ticket.brand
• ticket.collaborators
• ticket.comment
• ticket.comments
• ticket.conversation
• ticket.createdAt
• ticket.customField:fieldName
• ticket.customStatus
• ticket.description
• ticket.editor
• ticket.externalId
• ticket.form
• ticket.id
• ticket.isNew
• ticket.organization
• ticket.postSaveAction
• ticket.priority
• ticket.recipient
• ticket.requester
• ticket.sharedWith
• ticket.status
• ticket.statusCategory
• ticket.subject
• ticket.tags
• ticket.type
• ticket.updatedAt
• ticket.via
• ticket.viewers

Actions

• ticket.collaborators.add
• ticket.collaborators.remove
• ticket.tags.add
• ticket.tags.remove
• ticket.sendMessage
• disableSave
• enableSave

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 group
client.set('ticket.assignee', { groupId: <groupId>, userId: <userId> })

// Assign to a group only
client.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 Name	Description
web	Public agent, admin, and end-user comments from the Zendesk Support email channel
internal	Private agent and admin comments
voice	Call and voicemail recording comments from the Zendesk Talk channel
chat	Public agent, admin, and end-user messages from the Web Widget (Classic)
native_messaging	Public agent, admin, and end-user messages from Web and mobile messaging
line	Public agent, admin, and end-user messages from the LINE social messaging channel
wechat	Public agent, admin, and end-user messages from the WeChat social messaging channel
sunshine_conversations_twitter_dm	Public agent, admin, and end-user messages from the X (formerly Twitter) direct messages social messaging channel
sunshine_conversations_facebook_messenger	Public agent, admin, and end-user messages from the Facebook Messenger social messaging channel
instagram_dm	Public agent, admin, and end-user messages from the Instagram direct messages social messaging channel
whatsapp	Public agent, admin, and end-user messages from the WhatsApp social messaging channel
any_channel	Public end-user messages from Channel integrations
twitter	Public and private (X direct messages) end-user messages from the legacy public X channel
facebook	Public and private (Facebook Messenger) end-user messages from the legacy public Facebook channel
api	Public comments from the Support API
chat_transcript	If 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 Name	Message Content Type
web	text/html
internal	text/html
voice	null (call and voicemail recordings are included as attachments)
chat	text/plain
native_messaging	text/plain
line	text/plain
wechat	text/plain
sunshine_conversations_twitter_dm	text/plain
sunshine_conversations_facebook_messenger	text/plain
instagram_dm	text/plain
whatsapp	text/plain
any_channel	text/html
twitter	text/html
facebook	text/html
api	text/html
chat_transcript	text/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
• channel.sessionBased
• channel.sessionActive

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

• comment.attachments
• comment.text
• comment.type
• comment.useRichText

Actions

• comment.appendHtml
• comment.appendMarkdown
• comment.appendText

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

• attachment.contentType
• attachment.contentUrl
• attachment.filename
• attachment.thumbnailUrl

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
• brand.id
• brand.isActive
• brand.isDefault
• brand.logo
• brand.name
• brand.subdomain
• brand.url

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
}

brand.logo

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
• user.isIdle

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
• agreement.name
• agreement.partnerName

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

• ticketField.name
• ticketField.label
• ticketField.optionValues
• ticketField.optionGroups
• ticketField.isRequired
• ticketField.requiredOnStatuses
• ticketField.isVisible
• ticketField.isEnabled
• ticketField.type
• status.optionValues.{index}.label
• status.optionValues:{identifier}.label

Actions

• ticketField.disable
• ticketField.enable
• ticketField.hide
• ticketField.show
• ticketField.toggle

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

• ticketFieldOption.isEnabled
• ticketFieldOption.isVisible
• ticketFieldOption.label
• ticketFieldOption.value

Actions

• ticketFieldOption.disable
• ticketFieldOption.enable
• ticketFieldOption.hide
• ticketFieldOption.show
• ticketFieldOption.toggle

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

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

• macro.id
• macro.availability_type
• macro.description
• macro.title

Actions

• macro

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
• via.source

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.