Ticket and New Ticket sidebar
The app is displayed in theapps trayon 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 isNew.
默认情况下,应用程序栏中认为是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 CSSis a good way to do this, but there are other frameworks such asMaterializethat 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 themanifestfile'slocation.flexibleproperty 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}}},
In addition to the objects available inall 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 thecore 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, seeWorking 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, theticket.form.id.changedevent 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_.deferunderscore 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 theticketFields.[ticket field].optionValues.changedevent 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 theticket.custom_field_[custom field ID].changedevent 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,123123is 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
Thecomment.text.changedevent fires on a new ticket when the Description field is changed.
Wildcard change events
In addition to the specific.changedevents 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){varpropertyName=e.propertyName;// "ticket.assignee.user.email"varnewValue=e.newValue;// "[email protected]"handleChange(propertyName,newValue);});
Dynamic events can be useful for identifying and handling events that occur to fields that are installed usingapp requirements.
Ticket submission events
The following events correspond to the lifecycle of a ticket save action, which may be controlled by one or moreticket.savehook handlers. For more information, seeTicket 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 respondingticket.savehook 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 theUser 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 theticket.viewers.changedevent receives an array ofCollision User objectsas the first argument. These objects, in addition to all the methods available for theUser object, also haveisEditing()andisIdle()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 aticket.savehook 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});
Aticket.savehook 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 somethingreturntrue;});
If your app needs to do something asynchronous such as an AJAX request, use apromise.
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 somethingreturnfalse;});
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 apromise.
停止售票asynchrono保存操作us function, the promise must be rejected. Example:
client.on('ticket.save',async()=>{returnPromise.reject(false);});
Notifying the user if the ticket is not saved
When aticket.savehook 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.
自定义消息显示为一个错误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 somethingreturn"The ticket wasn't saved!";});
You can also supply the notification string as an argument to thereject()method in apromise.
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 yourmanifest 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 theticket.savehook. 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 theticket.savehook, 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 of60 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 theticket.savehook. SeeTicket 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
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}}}
SeeGroupandUserobject properties.
Limitations
- If the assignee field is disabled, a request to set the ticket assignee returns an error.
- To set an assignee with the
groupIdanduserIdparameters, 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
groupIdparameter but nouserIdparameter, the original user value will be set to null. - If you set the assignee to an online agent during a live chat in theZendesk 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}}
SeeBrand objectproperties.
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. SeeConfiguring CC and follower permissions.
get
client.get('ticket.collaborators')
returns
{"ticket.collaborators":[{// User object properties}]}
SeeUser objectproperties.
invoke
client.invoke('ticket.collaborators.add',{email:value})// orclient.invoke('ticket.collaborators.add',{id:value})
invoke
client.invoke('ticket.collaborators.remove',{email:value})// orclient.invoke('ticket.collaborators.remove',{id:value})
ticket.comment
The currently editing comment.
get
client.get('ticket.comment')
returns
{"ticket.comment":{//Comment object properties}}
SeeComment objectproperties.
ticket.comments
An array of existingComment Event objectsfrom the ticket conversations and events. These objects are different from the Comment object.
Note: This property doesn't return comments fromWeb Widget (Classic)ormessaging. To fetch these comments, use theticket.conversationproperty.
get
client.get('ticket.comments')
returns
{"ticket.comments":[{// Comment Event object properties}]}
Limits: 65k characters
ticket.conversation
A lightweight version ofticket.commentsthat returns ticket conversations and events, including messages fromWeb Widget (Classic)andmessaging.
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":ISO8601formatted date time// YYYY-MM-DDTHH:MM:SSZ}]}
Specifications
Supported channel names
| Channel Name | Description |
|---|---|
| web | Public agent, admin, and end-user comments from theZendesk Support email channel |
| internal | Private agent and admin comments |
| voice | Call and voicemail recording comments from theZendesk Talk channel |
| chat | Public agent, admin, and end-user messages from theWeb Widget (Classic) |
| native_messaging | Public agent, admin, and end-user messages fromWeb and mobile messaging |
| line | Public agent, admin, and end-user messages from theLINE social messaging channel |
| 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 theTwitter direct messages social messaging channel |
| sunshine_conversations_facebook_messenger | Public agent, admin, and end-user messages from theFacebook Messenger social messaging channel |
| instagram_dm | Public agent, admin, and end-user messages from the Instagram direct messages social messaging channel |
| Public agent, admin, and end-user messages from theWhatsApp social messaging channel | |
| any_channel | Public end-user messages fromChannel integrations |
| Public and private (Twitter direct messages) end-user messages from the legacyTwitter公共频道 | |
| Public and private (Facebook Messenger) end-user messages from the legacypublic Facebook channel | |
| api | Public comments from theSupport API |
| chat_transcript | 如果代理Workspace is enabled, the chat transcript message in ticket events fromWeb Widget (Classic)andmessaging. If Agent Workspace is not enabled, the chat transcript comment in the ticket conversations from Web Widget (Classic). |
Supported author roles
- "system" (Such as Answer 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 |
| text/plain | |
| sunshine_conversations_twitter_dm | text/plain |
| sunshine_conversations_facebook_messenger | text/plain |
| instagram_dm | text/plain |
| text/plain | |
| any_channel | text/html |
| text/html | |
| text/html | |
| api | text/html |
| chat_transcript | text/html |
Limitations
- The author id is
nullwhen the author has a "system" or "trigger" role.
ticket.customField:fieldName
The ticket custom field value as its defined type. Specify fieldName ascustom_field_.
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. SeeEnabling Ticket Statuses.
Note:Setting a custom ticket status triggers aticket.customStatus.changedevent. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers aticket.statusCategory.changedevent.
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:
>Couldnot find custom statuswithid671172
Note:: You can fetch a list of custom ticket statuses using aclient.get(ticketFields:status)call or the/api/v2/custom_statuses.jsonendpoint.
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":ISO8601formatted date time}
ticket.description
The ticket description.
get
client.get('ticket.description')
returns
{"ticket.description":string}
ticket.editor
The ticket editor. SeeTicket 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":{TicketFormobject properties}}
SeeTicket Form objectproperties.
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}}
SeeOrganization objectfor 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, orurgent.
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}}
SeeUser objectproperties.
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}]}
SeeSharing agreement objectproperties.
ticket.status
The ticket status.
get
client.get('ticket.status')
set
为一个新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 acustom ticket statustriggers aticket.customStatus.changedevent. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers aticket.statusCategory.changedevent.
client.set('ticket.status',value)
returns
{"ticket.status":string}
ticket.statusCategory
The ticket status category.
Note:Setting acustom ticket statustriggers aticket.customStatus.changedevent. Setting a custom ticket status may also change the ticket's status category. In this case, the change also triggers aticket.statusCategory.changedevent.
get
client.get('ticket.statusCategory')
set
为一个新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
valuesan array of tags (strings)
returns
{"ticket.tags":[//string]}
限制:5096个字符,骨料的所有标签
invoke
client.invoke('ticket.tags.add',value)// orclient.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, ortask.
client.get('ticket.type')
If the type istask, you can retrieve the task's due date, if any, with theticket.customField:fieldNameAPI. Specify 'due_date' as thefieldNameparameter.
client.get('ticket.type').then(function(data){if(data['ticket.type']==='task'){client.get('ticket.customField:due_date').then(function(data){vartaskDue=data['ticket.customField:due_date'];});}});
If the type isincident, you can retrieve the ID of the linked problem ticket, if any, with theticket.customField:fieldNameAPI. Specify 'problem_id' as thefieldNameparameter.
client.get('ticket.type').then(function(data){if(data['ticket.type']==='incident'){client.get(“ticket.customField: problem_id”).then(function(data){varproblemId=data[“ticket.customField: problem_id”];});}});
set
You can pass in one of the following values:question,incident,problem, ortask.
client.set('ticket.type',value)
If you set the type totask, you can set the task's due date with theticket.customField:fieldNameAPI. Specify 'due_date' as thefieldNameparameter.
client.set({'ticket.type':'task','ticket.customField:due_date':'2020/02/30'});
returns
{"ticket.type":string}
If you set the type toincident, you can set the ID of the linked problem ticket with theticket.customField:fieldNameAPI. Specify 'problem_id' as thefieldNameparameter.
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":ISO8601formatted date time}
ticket.via
Channel used to create the ticket, such as email, API, or web. The channel is represented as aVia object.
get
client.get('ticket.via')
returns
{"ticket.via":{//Via object properties}}
SeeVia objectproperties.
ticket.viewers
Other agents viewing the current ticket.
get
client.get('ticket.viewers')
returns
{"ticket.viewers":[{//Collision User object properties}]}
SeeCollision User objectproperties.
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}]}
SeeComment Attachment objectproperties.
comment.text
get
client.get('comment.text')
set
client.set('comment.text',value)
returns
{"comment.text":string}
In theZendesk Agent Workspace, settingcomment.textduring a chat conversation auto-transpiles rich text into plain text (Markdown syntax) in the chat editor.
comment.type
get
ReturnsfacebookPrivateMessage,facebookWallReply,internalNote,publicReply,twitterDirectMessage, ortwitterReply.
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 theUser objectandComment Attachment object, as well as thevia objectREST 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')
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 regularUser 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
Asharing agreementspecifies the terms under which ticket sharing can occur and how shared tickets are managed. SeeSharing tickets with other Zendesk Support accountsin Zendesk help, andSharing Agreementsin 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 benull.
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:
brandrequesterassigneecollaboratorticket_form_id(Enterprise only)tagstypeprioritysharedWith(if a ticket sharing agreement is enabled)due_dateorganization(if the requester is associated with multiple organizations)problemstatuscustom_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
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 asticketFields: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 useticketFieldactions oncustom ticket statusesin theticketFields:status.optionsorticketFields:status.optionValuesproperties.
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 ofoptionGroups.
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}}
SeeTicket Field Option objectproperties.
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 ofoptionValues.
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}}
SeeTicket Field Option objectproperties.
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 listedherecan 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":“字符串”}
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":“字符串”}
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 asticketFields: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:
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, seeVia Objectin 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)