All locations

Events

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

• Notification events
• Window events
• Talk Partner Edition events

Notification events

When a notification is sent to your app via the notify REST API endpoint, the framework triggers an event. For more information about the notify endpoint, see Send 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_name is 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 a User Object.

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

Window events

Apps have access to some common DOM window events through a window event namespace.

Note: Window events are debounced in 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

The window.resize event fires, at most, once every ~33 (1000/30) milliseconds.

Arguments

• width equivalent to window.innerWidth
• height equivalent to window.innerHeight

window.scroll

The window.scroll event fires, at most, once every ~16 (1000/60) milliseconds.

Arguments

• scrollTop equivalent to window.scrollTop

Talk Partner Edition events

Talk Partner Edition is required to use these events.

For potential integration features you can build with the API, see the Talk 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

The voice.dialout event fires when an agent clicks to call a phone number.

Arguments

• from can be user_phone_identity (user profile contact information section) or ticket_editor (from the call menu in the ticket editor)
• number the selected phone number
• userId the selected user's id
• ticketId the current ticket's id

voice.error

The voice.error event fires when an error occurs when subscribing to any other Talk Partner Edition events.

Arguments

• code can be 0 (unknown error) or 1 (forbidden which means Talk Partner Edition subscription must be purchased)
• message descriptive 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.

• Account object
• User object
• Group object
• Identity Object
• Time Zone object
• Apps Tray object

Additional properties

• visible

Additional actions

• hide
• show
• notify
• routeTo

The core events are also available to an app in all locations.

Account object

currentAccount

get

client.get('currentAccount')

returns

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

Properties

• account.planName
• account.subdomain
• account.daysLeftInTrial
• account.timeZone

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 the user sidebar location:

client.get('user')

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

• In any location:

  client.get('currentUser')

• In the ticket and new ticket sidebar:

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

User objects are also returned by other APIs, such as ticket.requester. In the following documentation, the <path_to_user> placeholder represents one of 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
• user.email
• user.groups
• user.organizations
• user.identities
• user.name
• user.role
• user.externalId
• user.locale
• user.details
• user.notes
• user.alias
• user.signature
• user.timeZone
• user.tags
• user.avatarUrl
• user.customField:field_name

user.id

get

client.get('<path_to_user>.id')

returns

{
  "<path_to_user>.id": integer
}

user.email

get

client.get('<path_to_user>.email')

returns

{
  "<path_to_user>.email": string
}

Limits: 255 characters

user.groups

get

client.get('<path_to_user>.groups')

returns

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

See Group object properties.

user.organizations

get

client.get('<path_to_user>.organizations')

returns

{
  "<path_to_user>.organizations": [{
    // Organization properties
  }]
}

See Organization object for the properties.

user.name

get

client.get('<path_to_user>.name')

returns

{
  "<path_to_user>.name": string
}

Limits: 255 characters

user.identities

get

client.get('<path_to_user>.identities')

returns

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

See Identity Object properties.

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('<path_to_user>.role')

returns

{
  "<path_to_user>.role": string | integer
}

user.externalId

get

client.get('<path_to_user>.externalId')

set

client.set('<path_to_user>.externalId', value)

returns

{
  "<path_to_user>.externalId": string
}

user.locale

get

client.get('<path_to_user>.locale')

returns

{
  "<path_to_user>.locale": string
}

user.details

get

client.get('<path_to_user>.details')

set

client.set('<path_to_user>.details', value)

returns

{
  "<path_to_user>.details": string
}

user.notes

get

client.get('<path_to_user>.notes')

set

client.set('<path_to_user>.notes', value)

returns

{
  "<path_to_user>.notes": string
}

user.alias

get

client.get('<path_to_user>.alias')

set

client.set('<path_to_user>.alias', value)

returns

{
  "<path_to_user>.alias": string
}

user.signature

get

client.get('<path_to_user>.signature')

set

client.set('<path_to_user>.signature', value)

returns

{
  "<path_to_user>.signature": string
}

user.timeZone

get

client.get('<path_to_user>.timeZone')

returns

{
  "<path_to_user>.timeZone": {
    //Time Zone object properties
  }
}

See the Time Zone object properties.

user.tags

get

client.get('<path_to_user>.tags')

returns

{
  "<path_to_user>.tags": [
    //strings
  ]
}

user.avatarUrl

get

client.get('<path_to_user>.avatarUrl')

returns

{
  "<path_to_user>.avatarUrl": string
}

user.customField:fieldName

The user custom field value as its defined type. Replace fieldName with the custom field's key attribute. User the User Fields REST API to get a list of possible key values.

Note: In some cases, the time format returned from the ticket.requester.customField:user_date_field API is not in the ISO8601 format.

get

client.get('<path_to_user>.customField:fieldName') // e.g. client.get('<path_to_user>.customField:my_text_field')

set

client.set('<path_to_user>.customField:fieldName', value) // e.g. client.set('<path_to_user>.customField:my_text_field', value)

returns

{
  "<path_to_user>.customField:fieldName": string
}

Group object

In this section, the <path_to_user> placeholder is used to represent the user. See the User object section for possible values.

Properties

• group.id
• group.name

group.id

get

client.get('<path_to_user>.groups.0.id')

returns

{
  "<path_to_user>.groups.0.id": integer
}

group.name

get

client.get('<path_to_user>.groups.0.name')

returns

{
  "<path_to_user>.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, an X (formerly Twitter) handle, or some other option.

The variable <path_to_user> is used in the following documentation. See the User Object documentation for the possible values of this variable.

Properties

• identity.id
• identity.type
• identity.value
• identity.verified
• identity.primary
• identity.userId
• identity.undeliverableCount
• identity.deliverableState

identity.id

get

client.get('<path_to_user>.identities.0.id')

returns

Returns the id of the identity.

{
  "<path_to_user>.identities.0.id": integer
}

identity.type

get

client.get('<path_to_user>.identities.0.type')

returns

Returns one of email, twitter, facebook, google, agent_forwarding, or phone_number.

{
  "<path_to_user>.identities.0.type": string
}

identity.value

get

client.get('<path_to_user>.identities.0.value')

returns

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

{
  "<path_to_user>.identities.0.value": string
}

identity.verified

get

client.get('<path_to_user>.identities.0.verified')

returns

Returns true if the identity has been verified.

{
  "<path_to_user>.identities.0.verified": boolean
}

identity.primary

get

client.get('<path_to_user>.identities.0.primary')

returns

Returns true if this identity is the primary identity.

{
  "<path_to_user>.identities.0.primary": boolean
}

identity.userId

get

client.get('<path_to_user>.identities.0.userId')

returns

Returns the id of the user.

{
  "<path_to_user>.identities.0.userId": integer
}

identity.undeliverableCount

get

client.get('<path_to_user>.identities.0.undeliverableCount')

returns

For an identity type of email, returns the number of times a soft-bounce response was received at that address. Maximum is 10, after which the deliverable_state is set to undeliverable.

{
  "<path_to_user>.identities.0.undeliverableCount": integer
}

identity.deliverableState

get

client.get('<path_to_user>.identities.0.deliverableState')

returns

For an identity type of email, returns either deliverable or undeliverable.

{
  "<path_to_user>.identities.0.deliverableState": string
}

Time Zone object

The <path_to_user> placeholder is used in the following documentation. See the User object documentation for the possible values of this variable.

Properties

• timezone.name
• timezone.translatedName
• timezone.ianaName
• timezone.offset
• timezone.formattedOffset

timezone.name

get

client.get('<path_to_user>.timeZone.name')

returns

{
  "<path_to_user>.timeZone.name": string
}

timezone.translatedName

get

client.get('<path_to_user>.timeZone.translatedName')

returns

{
  "<path_to_user>.timeZone.translatedName": string
}

timezone.ianaName

get

client.get('<path_to_user>.timeZone.ianaName')

returns

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

{
  "<path_to_user>.timeZone.ianaName": string
}

timezone.offset

get

client.get('<path_to_user>.timeZone.offset')

returns

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

{
  "<path_to_user>.timeZone.offset": string
}

timezone.formattedOffset

get

client.get('<path_to_user>.timeZone.formattedOffset')

returns

{
  "<path_to_user>.timeZone.formattedOffset": string
}

Apps Tray object

The appsTray object lets you show and hide the tray that contains sidebar apps.

appsTray

get

client.get('appsTray')

returns

{
  "appsTray":  {
    isVisible: boolean
  }
}

Properties

• appsTray.isVisible

Actions

• appsTray.show
• appsTray.hide

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 using client.invoke('hide').

get

client.get('visible')

returns

{
  "visible": true
}

Additional actions

• hide
• show
• notify
• routeTo

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])

// or

client.invoke('notify', message[, kind, options])

arguments

• message the 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 named sticky that 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)

// or

client.invoke('routeTo', 'ticket', 'new')

// or

client.invoke('routeTo', 'nav_bar', appName, appSection)

arguments

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

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

• new for 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 /agent/apps/app-name. 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')	/agent/apps/app-name/dashboard
  client.invoke('routeTo', 'nav_bar', 'app-name', 'greeting?p=hello+world')	/agent/apps/app-name/greeting?p=hello+world
  client.invoke('routeTo', 'nav_bar', 'app-name/foo?p=false')	/agent/apps/app-name/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.