Zopim is now known as Zendesk Chat. The REST API will continue to work as expected and there are no changes in terms of functionality.

Note: If you are participating in the Zendesk messaging beta, some Chat APIs are not supported. See How Zendesk messaging impacts Chat APIs for more information.

Zendesk Chat is a live chat solution that helps businesses increase sales conversion by engaging important leads on their websites. It is our goal to help many of these businesses use the Zendesk Chat API (the "API") to automate and enhance their customer support with Zendesk Chat.


This is the documentation for the Zendesk Chat REST API. Read the contents of this page carefully, including the Restrictions and Responsibilities, to understand how to be a good API citizen.

Endpoints are documented with the HTTP method for the request and a partial resource identifier. Example:

GET /api/v2/chats

Prepend https://www.zopim.com to the resource identifier to get the full endpoint URL:


The examples in the docs are cURL statements. You can run the statements on a command line to try out different API requests. To learn more, see Installing and using cURL. In Windows, you'll need to modify some of the examples in the docs to make them work. See Using cURL in Windows.

When documenting an API, we use curly braces, {}, to mean a value you must supply. Example: https://www.zopim.com/api/v2/chats/search?q=timestamp:{ISO-8601-timestamp}.

Document conventions

Access to most endpoints is restricted by Zendesk user role. The role is specified in the Allowed For section of an endpoint. The hierarchy of Zendesk user roles is as follows: owner, admins, agents, end users, and anonymous users. When the Allowed For section lists a role, any user with a higher level role implicitly also has access to the endpoint. For example, if the Allowed For section lists "Agents", then the owner and admins can use the endpoint too.

Security and Authentication

This API is an SSL-only API, regardless of how you may have your account configured. You must be a Zendesk Chat user to make API requests.

If you created your Zendesk Chat account in Zendesk Support, you must authenticate with an OAuth access token. See OAuth access token.

If you have a stand-alone Chat account that wasn't created in Zendesk Support, you can use either basic authentication with your username and password credentials, or an OAuth access token.

If you aren't sure what type of Chat account you have, see Determining your Zendesk Chat account version.

Basic authentication

You can use basic authentication only if your Chat account was not created in Zendesk Support.

Use the following authentication format with your email address and password:


curl -u [email protected]:password123 https://www.zopim.com/api/v2/agents/me

OAuth access token

The Zendesk Chat API supports OAuth authorization flows. See OAuth Authentication. In your requests, specify the access token in an Authorization header as follows:

Authorization: Bearer {access_token}

curl -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo" https://www.zopim.com/api/v2/agents/me

Rate Limiting

Each endpoint in the Chat API is rate limited at 200 requests per minute. Usage limits information is provided in the response header when a request is made. See Response Format.

If the rate limit is exceeded, Zendesk Chat will respond with a HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in.

Request Format

This is a JSON-only API. You must supply a Content-Type: application/json header on PUT and POST requests. You must set an Accept: application/json header on all requests. You may get a text/plain response in case of an error such as a bad request. You should treat this as an error you need to take action on.

Response Format

Zendesk Chat responds to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, Zendesk Chat renders the resulting JSON representation in the response body. Example:

HTTP/1.1 200 OKContent-Type: application/json
{	"item": {		"id": 123,		"name": "Wibble",		...		"created_at": "2012-04-04T09:14:57Z"	}}

The response also includes the following headers indicating the account's current rate limit and the number of requests remaining in the current minute:

X-RateLimit: 200X-RateLimit-Remaining: 199

Time stamps use UTC time and their format is ISO8601.

We respond to unsuccessful requests with HTTP status codes in the 400 range. The response may be "text/plain" content type for API level error messages (such as when trying to call the API without SSL). If you see a response from a known endpoint that looks like plain text, you probably made a syntax error in your REST call. If you ever experience responses with status codes in the 500 range, Zendesk Chat may be experiencing internal issues or having a scheduled maintenance (during which we send a 503 Service Unavailable status code). Please check @ZendeskOps and our status page in such cases for any known issues.

When building an API client, we recommend treating any 500 status codes as a warning or temporary state. However, if the status persists and we don't have a publicly announced maintenance or service disruption, contact us at Zendesk Customer Support.

Restrictions and responsibilities

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 and the other documentation we provide you. You must also comply with the restrictions set forth in the Terms of Service and the Privacy Policy that apply to your use of the Zendesk Chat Service, 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.

Change Policy

Zendesk Chat may modify the attributes and resources available to the API and our policies related to access and use of the API from time to time without advance notice. Zendesk Chat will use commercially reasonable efforts to notify you of any modifications to the API or policies through notifications or posts on the Zendesk Developer Website. Modification of the API may have an adverse effect on Zendesk Chat Applications, including but not limited to changing the manner in which Zendesk Chat Applications communicate with the API and display or transmit Your Data. Zendesk Chat will not be liable to you or any third party for such modifications or any adverse effects resulting from such modifications.