Introduction

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.

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.

The API

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:

https://www.zopim.com/api/v2/chats

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 your must supply. Example: https://www.zopim.com/api/v2/chats/search?q=timestamp:{ISO-8601-timestamp}.

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. You can authorize against the API using either basic authentication with your username and password credentials, or with OAuth.

Basic authentication

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

{email_address}:{password}

Example
curl -u jdoe@example.com:password123 https://www.zopim.com/api/v2/agents/me
OAuth access token

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

Authorization: Bearer {access_token}

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

Rate Limiting

This API is rate limited. We only allow a certain number of requests per minute. We reserve the right to adjust the rate limit for given endpoints in order to provide a high quality of service for all clients. As an API consumer, you should expect to be able to make at least 200 requests per minute.

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 OK
Content-Type: application/json

{
    "item": {
        "id": 123,
        "name": "Wibble",
        ...
        "created_at": "2012-04-04T09:14:57Z"
    }
}

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 @zopim 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 chat@zendesk.com.

Legal notices

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. Zendesk Chat also tracks deprecation of attributes of the API on its Changes Roadmap. 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.