Core Apps API

The following core events, properties, and actions are available in all locations in all products that support the Zendesk Apps framework:

Use the ZAF client in your app to listen for the events, access the properties, or invoke the actions.

This API is supplemented by the Support Apps API and the Chat Apps API.

Events

Note: The window events are debounced in apps for performance reasons. Debounce wait values are noted in each window event's description below.

app.registered

Fires when the app is loaded. It also fires when the app is reloaded, such as when the agent clicks the Reload All Apps button.

app.activated

Fires when the app becomes active. This can mean different things depending on the location. For example, if the app is in the ticket sidebar, the app becomes active when the user switches to the tab containing this instance of your app.

Note: This event differs from the app.registered event in that it fires when the app becomes active, not when the app is loaded. Use app.registered to listen for load events.

app.deactivated

Fires when the app becomes inactive. This can mean different things depending on the location. For example, if the app is in the ticket sidebar, the app becomes inactive when the user switches away from the tab containing this instance of your app.

app.expanded

Fires when the app is expanded from a collapsed state. This feature is only available in sidebar locations, which includes ticket sidebar, new ticket sidebar, user sidebar, organization sidebar and chat sidebar.

app.collapsed

Fires when the app is collapsed from an expanded state. This feature is only available in sidebar locations, which includes ticket sidebar, new ticket sidebar, user sidebar, organization sidebar and chat sidebar.

instance.created

Fires when another instance of your app is created. This is useful in cases where you want to interact with transient locations, like the ticket sidebar in Zendesk Support, from a permanent location, like the background location in Zendesk Support. Event handlers bound to instance.created receive the context data for the instance just created. You can use the instanceGuid property of the context to create a ZAFClient using the instance API. For more information about the Instances API see Messaging between locations.

Example:

// background location
client.on('instance.created', function(context) {
  if (context.location === 'ticket_sidebar') {
    var ticketInstance = client.instance(context.instanceGuid);
    ticketInstance.invoke('comment.appendText', 'Best regards!');
  }
});
window.resize

Fires when the current browser window is resized. The event fires, at most, once every ~33 (1000/30) milliseconds.

When invoked by this event, the handler function receives a jQuery event object as its first argument and the following additional arguments:

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

Fires when the current browser window is scrolled to a new position. The event fires, at most, once every ~16 (1000/60) milliseconds.

When invoked by this event, the handler function receives a jQuery event object as its first argument and the following additional argument:

  • scrollTop, equivalent to window.scrollTop

Properties

instances

Represents the running instances of the app. There is one instance for each iframe. For example, if there are two ticket tabs open in the agent interface and an app runs in the top_bar and ticket_sidebar locations, the app will have three instances.

You can use this API to establish cross-location communication and API calls. See client.instance for further usage details.

get
client.get('instances')
returns
{
  instances: {
    "9e012b1f-1397-484e-8810-c444b8085e55": {
      instanceGuid: "9e012b1f-1397-484e-8810-c444b8085e55"
      ...
    }
  }
}

Each instance is keyed by its instanceGuid. The contents of the instance object are equivalent to that iframe's context.

requirement

Returns an object containing a requirement_id and a requirement_type. For more information, see Setup - Specifying app requirements.

get
client.get('requirement:identifier')
returns
{
  "requirement:identifier": {
    "requirement_id": integer,
    "requirement_type": Resource type
  }
}

Note: Resource types available are listed in Setup - Declaring requirements.

assetURL

Returns a fully qualified URL pointing to a file in the app's assets directory.

get
client.get('assetURL:logo\\.png')
returns
{
  "assetURL:logo\.png": "https://.../logo.png"
}

Note: Dots and commas in the filename name must be escaped using a backslash. To add a single backslash in a string literal, you need to use "\\", as the first backslash escapes the second one. This can be demonstrated by console.log("\\");.

isCollapsed

Returns the current collapsed state of the app. This property is only available for sidebar locations, which includes ticket sidebar, new ticket sidebar, user sidebar, organization sidebar and chat sidebar.

get
client.get('isCollapsed')
returns
{
  "isCollapsed": true/false
}
viewport.size

Returns the size of the browser window viewport.

get
client.get('viewport.size')
returns
{
  "errors": {},
  "viewport.size": {
    "width": 1024,
    "height": 768
  }
}

Actions

resize

Resizes the app's iframe dimensions.

invoke
client.invoke('resize', { width: '300px', height: '750px' })
arguments
  • Object containing the desired dimensions (width and height in px, %, or vw/vh for modals)
returns

Object containing the resultant dimensions

Limitations

The resize API has the following limitations in some locations:

  • ticket, user, and organization sidebar apps cannot be wider than 320px
  • nav bar apps cannot be resized; they always take the maximum space available
  • top bar apps don't support percentage values; use pixel values
  • modals can take up to 80% of the viewport (80vh and 80vw)
instances.create

Creates a new iframe instance of the app in a specified location, such as a modal in Zendesk Support. See Modal. Additional locations may become available in the future.

invoke
client.invoke('instances.create', options)
arguments
  • options: an object with two mandatory properties. Valid values of the location property depend on the product. In Zendesk Support, the value must be set to modal. The url property must be set to the URL to be used for the new iframe. The URL can be an absolute URL or start with assets/ if it is relative to the uploaded app's assets directory.
returns

A promise resolving to an object containing metadata for the new instance.

{
  "instances.create": [
    instanceGuid: "9e012b1f-1397-484e-8810-c444b8085e55",
    ...
  ]
}

The returned promise resolves once the instance has been created by the framework. In the case of modals, the instance is only created once the modal is visible on the screen. It is delayed if another modal is already open since only one modal can be shown at a time.

The returned array always has one element. In a future location, this API may create more than one instance. In that case the array would be longer.