Zendesk Chat API

This document lists the app locations, properties, and actions you can use in apps running in Zendesk Chat. These APIs are supplemented by the Core APIs available to all Zendesk apps.

If you're just getting started, see Building your first Chat app.

Locations

The following locations are available for apps in Zendesk Chat:

For more information, see Setting the app location.

Objects

You can use the get, set, and invoke methods to asynchronously read and write data and invoke actions in the product interface. For more information about the get, set, and invoke methods themselves, see ZAF Client API.

All invoke methods are returned with a status object indicating their success. A successful status object would be of the form { <invoked method>: {'_status': 'ok'} }. On error this status object is not returned.

Background

No UI. Always running in the background to receive special events.

Example manifest

"location": {
  "chat": {
    "background": "assets/iframe.html"
  }
},

The following objects and event are available in this location.

Objects

Events

  • channel.chat.end

Chat Sidebar

Panel on the right side of the ongoing chat panel in Zendesk Chat.

Example manifest

"location": {
  "chat": {
    "chat_sidebar": "assets/iframe.html"
  }
},

Objects

Events

The following events are available in this location. See Working with framework events.

  • channel.chat.start
  • channel.chat.end
  • channel.department.changed
  • channel.message.received
  • channel.message.sent
  • channel.textarea.changed
  • channel.ticket.created
  • channel.window.inbackground
  • channel.window.infocus
  • visitor.display_name.changed
  • visitor.email.changed
  • visitor.phone.changed
  • visitor.notes.changed

Agents Object

Represents all the agents that are part of the chat currently being viewed.

Availability

chat_sidebar location.

Properties

agents

Gets the information of all the agents that are part of the chat.

get
client.get('agents');
returns
{
  "agents": {
    <agent_id> : {
      User object properties
    },
    ...
  }
}

See CurrentUser Object properties.

Chat Object

Represents the chat currently being viewed.

Availability

chat_sidebar location

chat

Retrieves the chat object, with all its properties.

get
client.get('chat')
returns
{
  "chat": {
    // Chat object properties
  }
}

Properties

Actions

chat.id

Retrieves the chat's id. Returns null if the chat has not started yet.

get
client.get('chat.id');
returns
{
  "chat.id": string
}
chat.department

Retrieves the chat's department. Returns null if the chat belongs to no department.

get
client.get('chat.department');
returns
{
  "chat.department": {
    "id": integer,
    "name": string
  }
}
chat.messages

Gets all the messages that have been sent in the chat.

get
client.get('chat.messages');
returns
{
  "chat.messages": [
    {
      "channel": string,
      "nick": "visitor:<visitor id>" or "agent:<agent id>",
      "display_name": string,
      "message": string,
      "ts": integer,
      "msg_lang_code": string
    }
    ...
  ]
}
chat.tags

Gets the existing chat tags.

get
client.get('chat.tags');
returns
{
  "chat.tags": Array of strings
}
chat.tags.add

Adds a tag to the existing chat tags.

invoke
client.invoke('chat.tags.add', value);
arguments
  • String of chat tag to be added.
notes
  • This action is permitted only if the agent with the app loaded is already part of the chat.
  • The tag to be added must be a part of the predefined tag list.
chat.tags.remove

Removes a tag from the existing chat tags.

invoke
client.invoke('chat.tags.remove', value);
arguments
  • String of chat tag to be removed.
notes

This action is permitted only if the agent with the app loaded is already part of the chat.

chat.joinChat

Allows the app to force the agent to join the chat.

invoke
client.invoke('chat.joinChat');
chat.sendChat

Allows the app to send a message to the chat on behalf of the agent viewing the chat.

invoke
client.invoke('chat.sendChat', value);
arguments
  • String of the message to be sent on the chat.
notes

This action is permitted only if the viewing agent is already part of the chat.

chat.postToChatTextArea

Allows the app to set a predefined message in the chat's own text area. This message is not sent on the chat unless the agent clicks the send button on the chat.

invoke
client.invoke('chat.postToChatTextArea', value);
arguments
  • String of the message to be shown on the chat's text area.
notes
  • This action is permitted only if the viewing agent is already part of the chat.
  • This action overwrites the content of the text area with the message.

CurrentAccount Object

Represents the account.

Availability

Any Zendesk Chat location.

currentAccount

Retrieves the current account object, with all its properties.

get
client.get('currentAccount');
returns
{
  "currentAccount": {
    // CurrentAccount Object properties
  }
}

Properties

currentAccount.key

Gets the account key of the current account.

get
client.get('currentAccount.key');
returns
{
  "currentAccount.key": string
}
currentAccount.zendesk

Gets the subdomain of the Zendesk Support account that is linked to the current account.

get
client.get('currentAccount.zendesk');
returns
{
  "currentAccount.zendesk": string
}

CurrentUser Object

Represents the current agent logged into the dashboard.

Availability

Any Zendesk Chat location.

currentUser

Retrieves the current logged in agent object, with all its properties.

get
client.get('currentUser');
returns
{
  "currentUser": {
    // CurrentUser Object properties
  }
}

Properties

currentUser.id

Gets the id of the current agent logged into the dashboard.

get
client.get('currentUser.id');
returns
{
  "currentUser.id": string
}
currentUser.name

Gets the display name of the current agent logged into the dashboard.

get
client.get('currentUser.name');
returns
{
  "currentUser.name": string
}
currentUser.first_name

Gets the first name of the current agent logged into the dashboard.

get
client.get('currentUser.first_name');
returns
{
  "currentUser.first_name": string
}
currentUser.last_name

Gets the last name of the current agent logged into the dashboard.

get
client.get('currentUser.last_name');
returns
{
  "currentUser.last_name": string
}
currentUser.email

Gets the email of the current agent logged into the dashboard.

get
client.get('currentUser.email');
returns
{
  "currentUser.email": string
}
currentUser.role

Gets the role of the current agent logged into the dashboard. The possible values returned are agent, admin or owner.

get
client.get('currentUser.role');
returns
{
  "currentUser.role": string
}
currentUser.admin

Gets a boolean indicating whether the current agent is an administrator of the account.

get
client.get('currentUser.admin');
returns
{
  "currentUser.admin":  boolean
}
currentUser.zendeskId

Gets the Zendesk Support user ID of the current agent logged into the dashboard.

get
client.get('currentUser.zendeskId');
returns
{
  "currentUser.zendeskId": integer
}
currentUser.locale

Gets the Zendesk Chat preferred language of the current user.

get
client.get('currentUser.locale');
returns
{
  "currentUser.locale": string
}

Visitor Object

Represents the visitor in the chat currently being viewed.

Availability

chat_sidebar location.

visitor

Retrieves the visitor object, with all its properties.

get
client.get('visitor')
set
client.set('visitor', {
  'visitor.name': value1,
  'visitor.email': value2,
  'visitor.phone': value3,
  'visitor.notes': value4
})
returns
{
  "visitor": {
    // Visitor object properties
  }
}

Properties

visitor.id

Gets the id of the visitor in the chat.

get
client.get('visitor.id');
returns
{
  "visitor.id": string
}
visitor.name

Gets or sets the name of the visitor in the chat.

get
client.get('visitor.name');
returns
{
  "visitor.name": string
}
set
client.set('visitor.name', value);
arguments
  • String of the name to be set for the visitor.
visitor.displayName

Similar to the visitor.name API, it can be used to get or set the name of the visitor in the chat.

get
client.get('visitor.displayName');
returns
{
  "visitor.displayName": string
}
set
client.set('visitor.displayName', value);
arguments
  • String of the name to be set for the visitor.
visitor.email

Gets or sets the email of the visitor in the chat.

get
client.get('visitor.email');
returns
{
  "visitor.email": string
}
set
client.set('visitor.email', value);
arguments
  • String of the email to be set for the visitor.
visitor.phone

Gets or sets the phone number of the visitor in the chat.

get
client.get('visitor.phone');
returns
{
  "visitor.phone": string
}
set
client.set('visitor.phone', value);
arguments
  • String of the phone number to be set for the visitor.
visitor.notes

Gets or sets the notes that have been written for the visitor in the chat.

get
client.get('visitor.notes');
returns
{
  "visitor.notes": string
}
set
client.set('visitor.notes', value);
arguments
  • String of the notes to be set for the visitor.
visitor.tags

Gets the tags assigned to the visitor.

get
client.get('visitor.tags');
returns
{
  "visitor.tags": Array of strings
}
visitor.pastChats

Gets the visitor's past chats.

get
client.get('visitor.pastChats');
returns
{
  "visitor.pastChats": Array of condensed Chat objects
}

See Chat Object properties.

visitor.pastVisits

Gets the pages previously visited by the visitor.

get
client.get('visitor.pastVisits');
returns
{
  "visitor.pastVisits": [
    {
      "timestamp": integer,
      "page_title": string,
      "page_url": string
    }
    ...
  ]
}
visitor.pageUrl

Gets the url of the page that the visitor is currently viewing on the site.

get
client.get('visitor.pageUrl');
returns
{
  "visitor.pageUrl": string
}
visitor.browser

Gets the browser being used by the visitor. Some of the possible values are Chrome, Firefox, Safari, etc.

get
client.get('visitor.browser');
returns
{
  "visitor.browser": string
}
visitor.platform

Gets the platform being used by the visitor. Possible values returned could be Mac OS, Windows, etc.

get
client.get('visitor.platform');
returns
{
  "visitor.platform": string
}
visitor.ip

Gets the ip of the visitor.

get
client.get('visitor.ip');
returns
{
  "visitor.ip": string
}
visitor.device

Gets the device being used by the visitor. Possible values are either desktop or mobile.

get
client.get('visitor.device');
returns
{
  "visitor.device": string
}
visitor.location

Gets the full name of the country in which the visitor is currently online.

get
client.get('visitor.location');
returns
{
  "visitor.location": string
}
visitor.userAgent

Gets the user-agent of the visitor.

get
client.get('visitor.userAgent');
returns
{
  "visitor.userAgent": string
}