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!');
  }
});

Note: The SDK client in that location might not have been registered yet when this event is fired. If your app needs to do something only after the SDK client has been registered, see instance.registered.

instance.registered

Fires when an app instance is loaded and registers a SDK client. It also fires when the app is reloaded, such as when the agent clicks the Reload All Apps button.

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"
      host: "zendesk",
      product: "support",
      location: "ticket_sidebar",
      account: {
        subdomain: "subdomain"
      },
      status: "registered"
      ...
    }
  }
}

Each instance is keyed by its instanceGuid. The contents of the instance object are equivalent to that iframe's context. The instance also includes a status property set to "created" after the instance is created and "registered" after the iframe is loaded and the SDK client has registered.

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 containing the following properties:
    • location a product-specific value. In Zendesk Support, the value must be set to modal.
    • url the URL of 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.
    • size (optional) object containing the desired dimensions (width and height in px, %, or vw/vh for modals)
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.