Documentation API Reference

All locations

Events

In addition to the core events, the following events are available to all locations in the Support product.

Notification events

When a notification is sent to your app via thenotify REST API endpoint, the framework triggers an event. For more information about the notify endpoint, seeSend Notification to App.

Use the following syntax to define a custom event handler. Custom event handlers should always be prefixed with "api_notification":

             

              
client.on("api_notification.event_name",function(data){console.log(data.body,data.sender);});

event_nameis the name of the event passed to the notify API by the sender. The event handler receives the notification's data and sender's information. The sender's information is aUser Object.

Note:Previously this was known as thenotificationevent, but it didn't have the sender argument.

Window events

Apps have access to some common DOMwindowevents through awindowevent namespace.

Note:Window events aredebouncedin apps for performance reasons. Debounce wait values are noted below under each event's description.

Available events:

Event Meaning
window.resize The current browser window was resized to a new size
window.scroll The current browser window was scrolled to a new position
window.resize

Thewindow.resize事件触发,最多一次~ 33 (1000/30) milliseconds.

Arguments

  • widthequivalent towindow.innerWidth
  • heightequivalent towindow.innerHeight
window.scroll

Thewindow.scrollevent fires, at most, once every ~16 (1000/60) milliseconds.

Arguments

  • scrollTopequivalent towindow.scrollTop

Talk Partner Edition events

Talk Partner Editionis required to use these events.

For potential integration features you can build with the API, see theTalk Partner Edition developer guide.

Available events:

Event Meaning
voice.dialout Agent clicked to call a phone number
voice.error Error occurred while subscribing to another Talk Partner Edition event
voice.dialout

Thevoice.dialoutevent fires when an agent clicks to call a phone number.

Arguments

  • fromcan beuser_phone_identity(user profile contact information section) orticket_editor(from the call menu in the ticket editor)
  • numberthe selected phone number
  • userIdthe selected user's id
  • ticketIdthe current ticket's id
voice.error

Thevoice.errorevent fires when an error occurs when subscribing to any other Talk Partner Edition events.

Arguments

  • 代码can be0(unknown error) or1(forbidden which means Talk Partner Edition subscription must be purchased)
  • messagedescriptive message about the error

Objects

The following objects, as well as a number of additional properties and actions, are available in all locations in the Support product.

Additional properties

Additional actions

Thecore eventsare also available to an app in all locations.

Account object

currentAccount

get
             

              
client.get('currentAccount')
returns
             

              
{"currentAccount":{// Account object properties}}

Properties

account.planName

get
             

              
client.get('currentAccount.planName')
returns
             

              
{"currentAccount.planName":string}

account.subdomain

get
             

              
client.get('currentAccount.subdomain')
returns
             

              
{"currentAccount.subdomain":string}

account.daysLeftInTrial

get
             

              
client.get('currentAccount.daysLeftInTrial')
returns
             

              
{"currentAccount.daysLeftInTrial":integer}

account.timeZone

get
             

              
client.get('currentAccount.timeZone')
returns
             

              
{"currentAccount.timeZone":{// Time Zone object properties}}

User object

user

get

You can use the 'user' argument to get a user object only in theuser sidebar地点:

             

              
client.get('user')

In other locations, you can get user objects with the following arguments:

  • In any location:

                   
    
                
    client.get('currentUser')

  • 机票和new ticket sidebar:

                   
    
                
    client.get('ticket.requester')// orclient.get('ticket.assignee.user')

User objects are also returned by other APIs, such asticket.requester. In the following documentation, the占位符代表之一the values above that returns a user object.

returns
             

              
{"currentUser":{// User object properties}}

or

             

              
{"ticket.requester":{// or "ticket.assignee.user"// User object properties}}

or

             

              
{"user":{// User object properties}}

Properties

user.id

get
             

              
client.get('.id')
returns
             

              
{".id":integer}

user.email

get
             

              
client.get('.email')
returns
             

              
{".email":string}

Limits: 255 characters

user.groups

get
             

              
client.get('.groups')
returns
             

              
{".groups":[{// Group object properties}]}

SeeGroup objectproperties.

user.organizations

get
             

              
client.get('.organizations')
returns
             

              
{".organizations":[{// Organization properties}]}

SeeOrganization object的属性。

user.name

get
             

              
client.get('.name')
returns
             

              
{".name":string}

Limits: 255 characters

user.identities

get
             

              
client.get('.identities')
returns
             

              
{".identities":[{//Identity object properties}]}

SeeIdentity Objectproperties.

user.role

get

Possible values are "end-user", "agent", "admin", or a custom role id if the user has a custom role on the Enterprise plan or above.

             

              
client.get('.role')
returns
             

              
{".role":string|integer}

user.externalId

get
             

              
client.get('.externalId')
set
             

              
client.set('.externalId',value)
returns
             

              
{".externalId":string}

user.locale

get
             

              
client.get('.locale')
returns
             

              
{".locale":string}

user.details

get
             

              
client.get('.details')
set
             

              
client.set('.details',value)
returns
             

              
{".details":string}

user.notes

get
             

              
client.get('.notes')
set
             

              
client.set('.notes',value)
returns
             

              
{".notes":string}

user.alias

get
             

              
client.get('.alias')
set
             

              
client.set('.alias',value)
returns
             

              
{".alias":string}

user.signature

get
             

              
client.get('.signature')
set
             

              
client.set('.signature',value)
returns
             

              
{".signature":string}

user.timeZone

get
             

              
client.get('.timeZone')
returns
             

              
{".timeZone":{//Time Zone object properties}}

See theTime Zone objectproperties.

user.tags

get
             

              
client.get('.tags')
returns
             

              
{".tags":[//strings]}

user.avatarUrl

get
             

              
client.get('.avatarUrl')
returns
             

              
{".avatarUrl":string}

user.customField:fieldName

The user custom field value as its defined type. Replace字段名with the custom field'skeyattribute. User theUser FieldsREST API to get a list of possiblekeyvalues.

get
             

              
client.get('.customField:fieldName')// e.g. client.get('.customField:my_text_field')
set
             

              
client.set('.customField:fieldName',value)// e.g. client.set('.customField:my_text_field', value)
returns
             

              
{".customField:fieldName":string}

Group object

In this section, theplaceholder is used to represent the user. See theUser objectsection for possible values.

Properties

group.id

get
             

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

              
{".groups.0.id":integer}

group.name

get
             

              
client.get('.groups.0.name')
returns
             

              
{".groups.0.name":string}

Identity Object

A user identity identifies a person in the Zendesk Support account. It's usually an email address, but it can also be a phone number, a Twitter handle, or some other option.

The variable is used in the following documentation. See theUser Objectdocumentation for the possible values of this variable.

Properties

identity.id

get
             

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

Returns the id of the identity.

             

              
{".identities.0.id":integer}

identity.type

get
             

              
client.get('.identities.0.type')
returns

Returns one ofemail,twitter,facebook,google,agent_forwarding, orphone_number.

             

              
{".identities.0.type":string}

identity.value

get
             

              
client.get('.identities.0.value')
returns

Returns the identifier for this identity, such as an email address or phone number.

             

              
{".identities.0.value":string}

identity.verified

get
             

              
client.get('.identities.0.verified')
returns

Returns true if the identity has been verified.

             

              
{".identities.0.verified":boolean}

identity.primary

get
             

              
client.get('.identities.0.primary')
returns

Returns true if this identity is the primary identity.

             

              
{".identities.0.primary":boolean}

identity.userId

get
             

              
client.get('.identities.0.userId')
returns

Returns the id of the user.

             

              
{".identities.0.userId":integer}

identity.undeliverableCount

get
             

              
client.get('.identities.0.undeliverableCount')
returns

For an identity type ofemail, returns the number of times a soft-bounce response was received at that address. Maximum is 10, after which thedeliverable_stateis set toundeliverable.

             

              
{".identities.0.undeliverableCount":integer}

identity.deliverableState

get
             

              
client.get('.identities.0.deliverableState')
returns

For an identity type ofemail, returns eitherdeliverableorundeliverable.

             

              
{".identities.0.deliverableState":string}

Time Zone object

Theplaceholder is used in the following documentation. See theUser objectdocumentation for the possible values of this variable.

Properties

timezone.name

get
             

              
client.get('.timeZone.name')
returns
             

              
{".timeZone.name":string}

timezone.translatedName

get
             

              
client.get('.timeZone.translatedName')
returns
             

              
{".timeZone.translatedName":string}

timezone.ianaName

get
             

              
client.get('.timeZone.ianaName')
returns

Returns the name of the time zone according to the IANA time zone database. Example: "America/Los_Angeles".

             

              
{".timeZone.ianaName":string}

timezone.offset

get
             

              
client.get('.timeZone.offset')
returns

Returns the number of minutes offset of the time zone relative to GMT.

             

              
{".timeZone.offset":string}

timezone.formattedOffset

get
             

              
client.get('.timeZone.formattedOffset')
returns
             

              
{".timeZone.formattedOffset":string}

Apps Tray object

TheappsTrayobject lets you show and hide the tray that contains sidebar apps.

appsTray

get
             

              
client.get('appsTray')
returns
             

              
{"appsTray":{isVisible:boolean}}

Properties

Actions

appsTray.isVisible

get
             

              
client.get('appsTray.isVisible')
returns
             

              
{"appsTray.isVisible":boolean}

appsTray.show

Shows the apps tray if hidden.

invoke
             

              
client.invoke('appsTray.show')
returns
             

              
{"appsTray.show":{"isVisible":true}}

appsTray.hide

Hides the apps tray.

invoke
             

              
client.invoke('appsTray.hide')
returns
             

              
{"appsTray.hide":{"isVisible":false}}

Additional properties

visible

Specifies if the app has been hidden usingclient.invoke('hide').

get
             

              
client.get('visible')
returns
             

              
{"visible":true}

Additional actions

hide

Hides the app.

invoke
             

              
client.invoke('hide')

show

Shows the app if hidden.

invoke
             

              
client.invoke('show')

notify

Displays a notification on the upper-right side of the agent interface.

invoke
             

              
client.invoke('notify',message[,kind,duration])// orclient.invoke('notify',message[,kind,options])
arguments

  • messagethe notification message. Supports HTML markup to format the string.

  • kind(optional) sets the background color of the notification box. Possible values:

    value background color
    'notice' green
    'alert' yellow
    'error' red

    If you omit the argument, the default value is 'notice'.

  • duration(optional) the duration (in milliseconds) that the notification is displayed. If you omit the argument, the default value is 4000.

  • options(optional) an object with a property namedstickythat takes a Boolean value. Controls whether the notification will stay open until the user intentionally closes it. If you omit the argument, the default value is{sticky: false}. To change it, use{sticky: true}.

routeTo

Opens a tab in the agent interface for a ticket, user profile, organization profile, view, or nav bar app.

invoke
             

              
client.invoke('routeTo',tabType,id)// orclient.invoke('routeTo','ticket','new')// orclient.invoke('routeTo','nav_bar',appName,appSection)
arguments

  • tabTypethe type of entity to open in the user interface. Can be'ticket','user','organization','views', or'nav_bar'.

  • id(optional forviews) the id of the entity to open as a number or a string.

  • newfor tickets, opens a new ticket tab in the agent interface.

  • appName(optional) for nav bar apps, a sanitized version of the app name to route to, where dashes replace underscores, spaces, or camel case in the name. For example,client.invoke('routeTo', 'nav_bar', 'app-name')routes to/代理/应用程序/应用名称. When omitted, defaults to the name of the app responsible for triggering this action.

  • appSection(optional) for nav bar apps, a section to route to within a nav bar app. Examples:

    action routes to
    client.invoke('routeTo', 'nav_bar', 'app-name', 'dashboard') /代理/应用程序/应用名称/dashboard
    client.invoke('routeTo', 'nav_bar', 'app-name', 'greeting?p=hello+world') /代理/应用程序/应用名称/greeting?p=hello+world
    client.invoke('routeTo', 'nav_bar', 'app-name/foo?p=false') /代理/应用程序/应用名称/foo?p=false, where the app name is part of the appSection.
returns

A promise that resolves only when the tab is successfully opened. The promise does not resolve with a useful value.