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.
The Conversations API is available on Zendesk Chat Enterprise or Premium (legacy) plan.
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
The Conversations API uses one of the following paths:
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.
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
Use the token to start an agent session with the Conversations API. See Start agent session in the Getting Started guide.
To optimize the WebSocket connection reliability, please follow the following best practices.
- Send regular pings to prevent being disconnected due to an idle connection.
You should receive an echo of the given payload if ping is successful.
- If the WebSocket connection is disconnected abnormally (for example, a disconnection without you stopping the session by
stopAgentSessionmutation), 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
startAgentSessionrequest, updating the agent status, and setting up the subscriptions again.
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.
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.
The Conversations API is rate limited.
|100 requests per second. A request can be a GraphQL
subscription, or "stop subscription"
|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:
|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.
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
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.
- Added support for string-based request id in websocket request/response payload.
- Added support for structured messages which include
sendListTemplatemutations. For more information, see Using structured messages in Zendesk Chat in the Chat Help Center.
- Added support for new department status of away.
DEPARTMENT_STATUSnow includes ONLINE, OFFLINE and AWAY.
- Fixed an issue to disallow tags with special characters in
addTagsmutation. The API now only allows alphanumeric characters, hyphens (-), and underscores (_) for tags.