Core Apps API

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

• Events
• Properties
• Actions

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, the Chat Apps API, and the Sell Apps API.

Events

• app.registered
• app.activated
• app.deactivated
• app.expanded
• app.collapsed
• instance.created
• instance.registered
• window.resize
• window.scroll

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.

Notes

• Apps in the top bar and nav bar load only when the user navigates to their locations and clicks on the app. This event occurs only when the app is first displayed.

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.

Notes

• 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.

• When an app is pinned or unpinned to the app shortcuts of an existing ticket, it will reload the same app in all other existing tickets. Similarly, if it is done in a new ticket, the app will be reloaded in all other new tickets. See Managing app shortcuts in Zendesk help.

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.

Note: There is no collapse state in app shortcuts. The expanded state will be true every time. When an app is pinned or unpinned, the state persists across tickets.

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 an 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 an event object as its first argument and the following additional argument:

• scrollTop, equivalent to window.scrollTop

Properties

• instances
• requirement
• assetURL
• isCollapsed
• viewport.size

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 Specifying app requirements.

get

client.get('requirement:identifier')

returns

{
  "requirement:identifier": {
    "requirement_id": string/integer,
    "requirement_type": Resource type
  }
}

requirement_id may return a string or an integer depending on the underlying object's ID. For example, ticket fields will return an integer but webhooks will return a string.

Note: Resource types available are listed in Specifying apps 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
• instances.create

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)

Note: Ensure that you always invoke a resize whenever the app.activated core event is fired if your app is dynamically calculating it's height. This is considered as a best practice to prevent a resizing issue where the body scrollHeight of the iframe would return a value of 0 whenever an agent switches to another ticket tab, while your app in the original tab was still in the process of being loaded.

You can use a resize event listener to automatically adjust the height of your app when its width changes in ticket sidebar or new ticket sidebar. For example:

window.addEventListener('resize', debounce(() => {
   console.log('innerWidth', window.innerWidth);
   resizeApp();
}, 200));

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.