Real Time Chat API

The Real Time Chat API provides programmatic access to ongoing activity on your Zendesk Chat account.

You can use the Real Time Chat API to do the following:

  • Display chats and agents metrics
  • Create and display a real time dashboard
  • Monitor a specific department
  • Predict or estimate capacity and other derived metrics

The Real Time Chat API has two components: a streaming WebSocket-based API and a REST API:

  • The Streaming API allows you to receive events from Zendesk Chat after you subscribe to one or several business metrics
  • The REST API allows you to pull data on-demand

All metrics are supported by both the Streaming API and the REST API.

This API is an SSL-only API. You must be a verified user to make API requests. You can authorize against the API using OAuth2. Important: Because each request must include the OAuth2 access token, we strongly advise against using this API from a non-secure environment. Example: Storing the token in a user-facing application and calling the API directly from the browser. The ideal use case for this API is a secured server environment where the sensitive data and requests are well protected.

Chat Metrics

The following lists the metrics related to chat activity on your Zendesk Chat account.

Metric key Format Time window Description
incoming_chats Number of chats Chat requests that are not currently assigned to any agent
assigned_chats Number of chats Chat requests that have been assigned to an agent, but not yet served by the agent
missed_chats Number of chats last 30 or 60 minutes Number of chat requests not served by any agent before the visitor leaves over the time window
active_chats Number of chats Number of chats that your agents are currently serving
waiting_time_avg Duration in seconds Average time that visitors have been waiting for their chat request to be served
waiting_time_max Duration in seconds Longest time that any visitor currently in queue has been waiting for their chat request to be served
chat_duration_avg Duration in seconds Average duration of all chats currently served
chat_duration_max Duration in seconds Longest duration for any chat currently served
response_time_avg Duration in seconds Average time that visitors have been waiting for an agent reply
response_time_max Duration in seconds Longest time that any visitor has been waiting for an agent reply
satisfaction_good Number of ratings last 30 or 60 minutes Number of chats rated good over the time window
satisfaction_bad Number of ratings last 30 or 60 minutes Number of chats rated bad over the time window
Null values

All metrics can be null if data has not yet been computed for your account or after a long period of inactivity.

Duration metrics will be null if not applicable to any chat. For instance, if no chat is waiting in the queue, waiting_time_avg and waiting_time_max will be null.

Agent Metrics

The following lists the metrics related to agents activity on your Zendesk Chat account.

Metric key Format Description
agents_online Number of agents Number of agents currently logged in with Online status
agents_away Number of agents Number of agents currently logged in with Away status
agents_invisible Number of agents Number of agents currently logged in with Invisible status
Null values

All metrics can be null if data has not yet been computed for your account or after a long period of inactivity.

Streaming API

The Streaming API provides read-only access to a selected set of business metrics. Once your application establishes a connection to a streaming endpoint, a feed of events is delivered to your app.

Rate Limiting

We only allow a certain number of new connections per minute. The number of new connections to the Streaming API is restricted by REST API rate limits. We also allow a certain number of concurrently running connections to the Streaming API. As a Streaming API consumer, you should expect to be able to have at most 1000 concurrent connections.

The events delivered by the Streaming API are not restricted by any rate limit.

We reserve the right to adjust the rate limit for given endpoints in order to provide a high quality of service for all clients. 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.

Using The API
  1. Establish an authenticated WebSocket connection to wss://rtm.zopim.com/stream.
  2. Subscribe to one or several metrics.
  3. Process incoming events.
  4. Unsubscribe to metrics.
Allowed For
  • Owner
  • Administrator
  • Agent
Establish Connection

Connect to the wss://rtm.zopim.com/stream WebSocket endpoint using your API OAuth token.

# This example uses the Node.js 'ws' library to create a WebSocket connection to the API from a server.
var WebSocket = require('ws');

var ws_client = new WebSocket(
  'wss://rtm.zopim.com/stream', {
    headers: {
      'Authorization': 'Bearer ' + {OAuth2 access token}
    }
  }
);

ws_client.on('open', function() {
  console.log('Successfully connected');
});
Subscribe To Chat Metric

Once connection is established, you can send messages to subscribe to individual metrics. Refer to Chat Metrics for the metric key.

{
  topic: "chats.{metric_key}",
  action: "subscribe"
}
Subscribe To Chat Metric On A Time Window

For metrics on a time window, a window size is required when subscribing. Refer to Chat Metrics to check metrics associated to a time window.

{
  topic: "chats.{metric_key}",
  action: "subscribe",
  window: {window_size_in_minutes}
}

Available time windows are 30 minutes and 60 minutes.

Subscribe To Chat Metric For A Department

You can optionally subscribe to a metric for a specific department. To list all the departments on your account or to fetch a department by name, use the Departments API.

{
  topic: "chats.{metric_key}",
  action: "subscribe",
  department_id: {department_id}
}
Process Incoming Chat Events

Once you have subscribed to one or several metrics, listen to subsequent messages to start collecting data.

ws_client.on('message', function(event) {
  console.log('Received message from server: ' + event);
  var message = JSON.parse(event);

  if (message.status_code !== 200) {
    console.log('Invalid status code ' + message.status_code);
    return;
  }

  if (message.content && message.content.type == 'update') {
    console.log('Metrics data received');
    ...
  }
};

The following are sample messages received after subscribing to several Chat metrics for a 30-minute time window. Please note that no department_id has been requested on subscription, hence it is null in the messages. Also note the 30-minute window provided on missed_chats.

{
  "content": {
    "topic": "chats",
    "data": {
      "incoming_chats": 2
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
{
  "content": {
    "topic": "chats",
    "data": {
      "assigned_chats": 0
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
{
  "content": {
    "topic": "chats",
    "data": {
      "waiting_time_avg": 12
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
{
  "content": {
    "topic": "chats",
    "data": {
      "missed_chats": {
        "30": 1
      }
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Subscribe to Agent Metric

As in the Chat metrics, you can subscribe to metrics related to agents connected to your Zendesk Chat account. Refer to Agent Metrics for the metric key.

{
  topic: "agents.{metric_key}",
  action: "subscribe"
}
Subscribe To Agent Metric For A Department

As in the Chat metrics, you can subscribe to agent-related metrics for a specific department. To list all the departments on your account or to fetch a department by name, use the Departments API.

{
  topic: "agents.{metric_key}",
  action: "subscribe",
  department_id: {department_id}
}
Process Incoming Agent Events

The following are sample messages received after subscribing to several Agent metrics for a specific department_id.

{
  "content": {
    "topic": "agents",
    "data": {
      "agents_online": 26
    },
    "type": "update",
    "department_id": 5
  },
  "status_code": 200
}
{
  "content": {
    "topic": "agents",
    "data": {
      "agents_away": 0
    },
    "type": "update",
    "department_id": 5
  },
  "status_code": 200
}
{
  "content": {
    "topic": "agents",
    "data": {
      "agents_invisible": 1
    },
    "type": "update",
    "department_id": 5
  },
  "status_code": 200
}
Unsubscribe

Once you stop processing some data, you can individually unsubscribe from a metric. Events will then stop being pushed on the connection.

{
  topic: "{chats or agents}.{metric_key}",
  action: "unsubscribe"
}

REST API

The Real Time Chat API also provides REST endpoints if your intention is to pull data on demand instead. If your intention is to monitor or process metrics in real time, consider using the Streaming API instead.

You must be a verified user to make API requests. You can authorize against the API using OAuth2. As in the Streaming API, we strongly recommend to use this API only in a secured server environment.

Example:

curl https://rtm.zopim.com/stream/{resource} \
  -H "Authorization: Bearer {API access token}"
Allowed For
  • Owner
  • Administrator
  • Agent
Data Initialization

If data has not yet been computed for your account or after a long period of inactivity, the REST API will temporarily return Not Computed response message.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status_code": 200,
  "message": "Not Computed!"
}
Get All Chat Metrics

GET /stream/chats

This captures all the chat activity for your account.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "chats",
    "data": {
      "incoming_chats": 2,
      "assigned_chats": 0,
      "waiting_time_avg": 12,
      "missed_chats": {
        "30": 1,
        "60": 1
      },
      "active_chats": 7,
      ...
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Get Single Metric for Chats

GET /stream/chats/{metric_key}

This returns a single chat metric for your account. Refer to Chat Metrics above for the metric name.

Example Response

GET /stream/chats/missed_chats

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "chats",
    "data": {
      "missed_chats": {
        "30": 1,
        "60": 2
      }
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Get Chat Metrics by Department

GET /stream/chats?department_id={department_id}

GET /stream/chats/{metric_key}?department_id={department_id}

This captures the chat activity for a specific department. To list all the departments on your account or to fetch a department by name, use the Departments API.

To capture activity for the chats which do not belong to any department, use department_id=0.

Example Response

GET /stream/chats?department_id=5

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "chats",
    "data": {
      "incoming_chats": 0,
      "waiting_time_avg": null,
      "missed_chats": {
        "30": 0,
        "60": 0
      },
      ...
    },
    "type": "update",
    "department_id": 5
  },
  "status_code": 200
}
Get Chat Metrics for a Specific Time Window

GET /stream/chats?window={window_size_in_minutes}

GET /stream/chats/{metric_key}?window={window_size_in_minutes}

This filters the chat metrics for the given time window.

Refer to Chat Metrics to check metrics associated to a time window. Other metrics remains unaffected.

Available time windows are 30 minutes and 60 minutes.

Example Response

GET /stream/chats/missed_chats?window=30

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "chats",
    "data": {
      "missed_chats": {
        "30": 1
      }
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Get All Agents Status

GET /stream/agents

This counts all the agents for your account.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "agents",
    "data": {
      "agents_online": 27,
      "agents_away": 1,
      "agents_invisible": 1
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Get Single Status for Agents

GET /stream/agents/{metric_key}

This returns a single metric for agents in your account. Refer to Agent Metrics above for the metric name.

Example Response

GET /stream/agents/agents_online

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "agents",
    "data": {
      "agents_online": 27
    },
    "type": "update",
    "department_id": null
  },
  "status_code": 200
}
Get Agents Status by Department

GET /stream/agents?department_id={department_id}

GET /stream/agents/{metric_key}?department_id={department_id}

This counts the agents for a specific department. To list all the departments on your account or to fetch a department by name, use the Departments API.

To count the agents who do not belong to any department, use department_id=0.

Example Response

GET /stream/agents?department_id=5

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": {
    "topic": "agents",
    "data": {
      "agents_online": 26,
      "agents_away": 0,
      "agents_invisible": 1
    },
    "type": "update",
    "department_id": 5
  },
  "status_code": 200
}