Chat Conversations API

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.


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

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

See the following resources to learn more about GraphQL:

API path

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 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), reconnect to the same authenticated WebSocket URL. You should be able to resume the session without the need to setup again (update agent status and setup subscription).


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
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 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 about the Chat Conversations API, please check our community forum. Feel free to post a question if no one has asked it before.


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 Zendesk Master Subscription 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.