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.

Example manifest

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

See Setting the app location.

In addition to the objects available in all locations, the following objects and additional 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.custom_field_[custom field ID].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.subject.changed
  • ticket.tags.changed
  • ticket.type.changed

The events fire when the respective properties on the ticket change due to user interaction or when Zendesk Support first loads the ticket. 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.

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.

If the promise is rejected, the save action is canceled.

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 30 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
client.set('ticket.assignee', { userId: value1, groupId: value2 })
returns
{
  "ticket.assignee": {
    "group": {
      // Group object properties
    }
    "user": {
      // User object properties
    }
  }
}

See Group and User object properties.

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)
returns
{
  "ticket.brand": {
    //Brand object properties
  }
}

See Brand object properties.

ticket.collaborators

The list of collaborators (followers and/or CC's) on the ticket.

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. These objects are different from the Comment object.

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

Limits: 65k characters

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

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
returns
{
  "ticket.requester": {
    //User object properties
  }
}

See User object properties.

ticket.sharedWith

The ticket shared agreement.

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

See Sharing agreement object properties.

ticket.status

The ticket status

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

You can pass in one of the following values: open, pending, solved.

client.set('ticket.status', value)
returns
{
  "ticket.status": 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', value)
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)
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.

Comment object

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

Properties

Actions

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

See 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
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 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
get
client.get('comment.attachments.0.thumbnailUrl')
returns
{
  "comment.attachments.0.thumbnailUrl": string
}
attachment.token

Returns the token of the current attachment for uploading more attachments. See the Attachment API in the REST API docs.

get
client.get('comment.attachments.0.token')
returns
{
  "comment.attachments.0.token": 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": [{
        // Attachment object properties
      }],
      "nonImageAttachments": [{
        // Attachment object properties
      }]
    }
  ]
}

See the User object and 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')
brand.logo
get
client.get('ticket.brand.logo')
returns
{
  "ticket.brand.logo": 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 Help Center, and Sharing Agreements in the REST API docs.

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)
  • 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`.

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

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

Viewing and changing the status button label text. Note, an index number needs to be provided.

get
client.get('ticketFields:status.optionValues.{index}.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"
}
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
set
client.get('ticket.form.id')
get
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:

Properties

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
}

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.

Additional actions

The following actions are available in this location:

disableSave
invoke
client.invoke('disableSave')
enableSave
invoke
client.invoke('enableSave')
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)