Chat Conversations API

⚠️ As of Jan 01, 2022, the Chat Conversations API is in maintenance mode and will not be receiving new features. Bug and security fixes will continue when required. Messaging customers can refer to Sunshine Conversations for Bots as a replacement option.

The Chat Conversations API lets your application act as a Zendesk Chat agent and interact with customers who use the Zendesk Web Widget or the Zendesk Chat Widget. The API is a GraphQL API, the first for Zendesk.

In addition to the Web Widget and Chat Widget, the API works with the chat functionality provided by the Mobile Chat SDK for Android and iOS, as well as the Web SDK.

The Conversations API is available on Zendesk Chat Enterprise or Premium (legacy) plan.

Documentation

For a hands-on tutorial on using the Conversations API, see Getting started with the Conversations API in the Develop Help Center.

The reference documentation for the Conversations API is available at https://zendesk.github.io/conversations-api/.

The Conversations API is the first GraphQL API released by Zendesk. The docs are hosted on a separate site to take advantage of the GraphQL schema. One benefit of using GraphQL is that high-quality API documentation can be generated directly from the GraphQL schema.

Zendesk is investigating solutions for generating and publishing GraphQL docs on developer.zendesk.com.

See the following resources to learn more about GraphQL:

• Introduction to GraphQL on the graphql.org website
• How to GraphQL website
• GraphQL specification website
• awesome-graphql on Github

API path

The Conversations API uses one of the following paths:

WebSocket

wss://chat-api.zopim.com/stream/0.1/graphql/{session_id}:{client_id}

HTTP

POST https://chat-api.zopim.com/graphql/request

Use HTTP for authentication. Make all other requests through a WebSocket connection.

The Chat REST API is unaffected by the introduction of the new path for the Conversations API.

Authentication

The Conversations API uses OAuth2 for authentication. To generate an OAuth access token, see OAuth Authentication in the Chat REST API documentation. Set the scope of the token to read, write, and chat.

Use the token to start an agent session with the Conversations API. See Start agent session in the Getting Started guide.

Managing WebSocket

To optimize the WebSocket connection reliability, please follow the following best practices.

1. Send regular pings to prevent being disconnected due to an idle connection.

{
  "sig": "PING",
  "payload": "<any_payload>"
}

You should receive an echo of the given payload if ping is successful.

{
  "sig": "PONG",
  "payload": "<any_payload>"
}

1. If the WebSocket connection is disconnected abnormally (for example, a disconnection without you stopping the session by stopAgentSession mutation), it is recommended to reconnect to the same authenticated WebSocket URL immediately to be able to resume the session without needing to set up again. If the session can't be recovered, you will need to set up the session again by making a startAgentSession request, updating the agent status, and setting up the subscriptions again.

Structured Messages

You can use the Conversations API to send structured messages to your visitor. Compared to the traditional plain text messages, structured messages provide a richer chat experience by including quick reply suggestions, templates, and interactive buttons. For more information, see Using structured messages in Zendesk Chat in the Chat Help Center.

Pagination

The Conversations API uses the Relay connection model to provide a standard mechanism for slicing and paginating result sets. See Relay Cursor Connections Specification on the Facebook Github website for more information.

Rate limits

The Conversations API is rate limited.

Description	Limit
Requests	100 requests per second. A request can be a GraphQL query, mutation (except startAgentSession), subscription, or "stop subscription"
startAgentSession requests	1 request per second or 50 requests per hour (whichever is reached first)
Subscription data published	50,000 subscriptions data per second

The Conversations API is also limited by the following factors:

Description	Limit
Maximum depth of query	GraphQL queries have a maximum depth of 11
Maximum number of concurrent subscriptions	An agent session can only have a maximum of 10 GraphQL subscriptions at a time

The rate limits are different from the traditional REST API rate limits because of the nature of GraphQL. One GraphQL request can replace multiple REST requests.

There is currently no endpoint to retrieve rate limits status. If needed, please track your own usage.

Rate limits are subject to change.

Limitations

The Conversations API has the following limitations:

• Does not support Chat roles and permissions available on the Enterprise plan. Agents whose sessions were created by the Conversations API do not comply with any set roles and permissions
• Does not fully support assigned chat routing in Chat. Assigned chat routing only works if the agent using the Conversations API is the only agent in the department

FAQ

If you have any questions, head over to the Chat Conversations API community. Feel free to post a question if no one has asked it before.

Changelog

9 Sept 2020

• Added msg_id argument to sendMessage mutation.
• Added msg_id field to Message type.

7 April 2020

• Exposed raw_id field of Visitor, VisitorChannel, Agent and Department types.

1 April 2020

• Added support for string-based request id in websocket request/response payload.

2 July 2019

• Added graphQLSubscriptions query.

6 June 2019

• Added current_ip field to Visitor type.
• Added ip field to VisitorChannel type.

27 February 2019

• Added support for structured messages which include sendQuickReplies, sendButtonTemplate, sendPanelTemplate, sendPanelTemplateCarousel, and sendListTemplate mutations. For more information, see Using structured messages in Zendesk Chat in the Chat Help Center.

12 February 2019

• Added external_id field to Visitor type.

7 January 2019

• Added support for new department status of away. DEPARTMENT_STATUS now includes ONLINE, OFFLINE and AWAY.

28 November 2018

• Added agents query.

24 August 2018

• Fixed an issue to disallow tags with special characters in addTags mutation. The API now only allows alphanumeric characters, hyphens (-), and underscores (_) for tags.

Legal Notices

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our API Restrictions and Responsibilities, in our Change Policy, and in the other documentation we provide you. You must also comply with the restrictions set forth in the Main Services Agreement and the Zendesk Privacy Policy, in all uses of the API. If Zendesk believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.