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.

Time-based metrics such as waiting_time_avg are delivered in the feed when a metric changes in response to an event affecting the metric's value. Such events include a visitor or agent joining a chat, leaving a chat, or sending a message, an agent transfering department, or the chat ending.

Using the streaming API consists of the following steps:

• Open a WebSocket connection. See Establishing a connection.
• Subscribe to one or more metrics. See Subscribing to metrics.
• Collect data. See Processing incoming events

If you decide to stop collecting data for a metric, you can unsubscribe from it. See Unsubscribing from a metric.

Allowed For

• Owner
• Administrator
• Agent

Rate Limits

Only a certain number of new connections to the Streaming API are allowed per minute. The number of new connections is restricted by the REST API rate limit of 200 requests per minute. Authenticating and establishing one web socket connection to the Streaming API counts as one request in the 200 requests per minute. For example, in one minute you can make 190 REST API requests and establish 10 new connections before both are rate limited.

Also, only a certain number of concurrently running connections to the Streaming API are allowed. As a Streaming API consumer, each account is expected to be able to have at most 1000 concurrent connections and each agent to have at most 10 concurrent connections.

Once a connection is open, you can receive an unlimited number of metric or event changes. These don't count towards any set rate limit.

Zendesk reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients.

If either the account or agent 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.

Establishing a connection

To open a connection, connect to the wss://rtm.zopim.com/stream WebSocket endpoint using your API OAuth token.

The following 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');
});

Subscribing to metrics

Once a connection is established, you can subscribe to a metric with a message that specifies a metric key. See Chat Metrics or Agent Metrics for the metric keys.

To subscribe to a chat metric, use the following format:

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

To subscribe to an agent metric, use the following format:

{
  topic: "agents.{metric_key}",
  action: "subscribe"
}

Subscribing to a metric with a time window

Some chat metrics have a time window. You must specify a window size when subscribing to them. See Chat Metrics for metrics with a time window.

Note: None of the agent metrics have a time window.

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

Available time windows are 30 minutes and 60 minutes.

Subscribing to a metric for a department

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

For chat metrics:

{
  topic: "chats.{metric_key}",
  action: "subscribe",
  department_id: {department_id}
}

For agent metrics:

{
  topic: "agents.{metric_key}",
  action: "subscribe",
  department_id: {department_id}
}

Processing incoming events

Once subscribed to one or several metrics, you can start collecting data from the incoming events. In the following example, the WebSocket client listens for the incoming events. The client was created using the Node.js ws library. See Establishing a connection.

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');
    ...
  }
};

Example chat events

The following are sample messages received after subscribing to several chat metrics for a 30-minute time window. The department_id is null when you don't specify a department when you subscribe to the metric. 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
}

Example 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
}

Unsubscribing from a metric

Once you want to stop collecting data for a metric, you can unsubscribe from the metric. Events will then stop being pushed on the connection.

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