Chat API

Chats

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.

You can use the API to get, set, or search chat information.

JSON Format

The API supports the following types of chats, with a different JSON object representation for each type:

  • Support chats
  • Offline Messages

Support Chat

Name Type Read-only Description
id string yes The ID of the chat
visitor object yes Information about the visitor
type string yes Chat type. One of offline_msg, chat
started_by string yes Who started the chat. Can be one of visitor, agent or trigger
session object yes Information related to the session of the session of the chat
timestamp timestamp yes Timestamp for the chat
count object yes Number of messages (each) by the visitor and the agent(s)
duration timestamp yes Duration of the chat
department_id integer yes The ID of the department to which the chat is directed
department_name integer yes The name of the department to which the chat is directed
response_time object yes Statistics about the response times in the chat, avg, max and first
agent_names array yes Names of agents involved in the chat
agent_ids array yes IDs of agents involved in the chat
triggered boolean yes Whether the chat was a triggered chat or not
triggered_response boolean yes Whether the response was a triggered response or not
unread boolean no Whether the chat is unread
missed boolean yes Whether the chat was missed or not
history array yes Chronological list of messages in the chat
conversions array yes Last 20 conversions (if any) attributed to the chat
tags array no Tags associated with the chat
rating string no The customer satisfaction rating for the chat
comment string no The customer comment on the chat
webpath array yes The list of pages the customer navigated to during the chat
zendesk_ticket_id integer yes The ID of the Zendesk Support ticket created from this chat. Available only if using version 2 of the Zendesk Chat-Support integration

Offline Message

Name Type Read-only Description
id string yes The ID of the chat
department_id integer yes The ID of the department to which the chat is directed
department_name integer yes The name of the department to which the chat is directed
visitor object yes Information about the visitor
type string yes Chat type. One of offline_msg, chat
session object yes Information related to the chat session
timestamp timestamp yes Timestamp for the chat
unread boolean no Whether the chat is unread
message string yes Message of the chat
zendesk_ticket_id integer yes The ID of the Zendesk Support ticket created from this chat. Available only if using version 2 of the Zendesk Chat-Support integration

List All Chats

GET /api/v2/chats

Allows an account owner/administrator to list all the chats for the account.

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats \
  -v -u {email_address}:{password}
Example Response
 
HTTP/1.1 200 OK
Content-Type: application/json

{ "chats":
  [
    {
      "id": "123",
      "visitor": {
          "id": "123",
          "phone": "",
          "notes": "",
          "email": "",
          "name": "Visitor 7"
      },
      "type": "chat",
      "started_by": "visitor",
      "session": {
          "city": "Orlando",
          "end_date": "2014-10-09T05:46:47Z",
          "ip": "67.23.229.96",
          "region": "Florida",
          "id": "141009.655464.1KhqS0Nw",
          "platform": "Mac OS",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10) AppleWebKit/600.1.25 (KHTML, like Gecko) Version/8.0 Safari/600.1.25",
          "country_code": "US",
          "country_name": "United States",
          "start_date": "2014-10-09T05:28:31Z",
          "browser": "Safari"
      },
      "timestamp": "2014-10-09T05:28:35Z",
      "count": {
          "visitor": 1,
          "total": 1,
          "agent": 0
      },
      "duration": 913,
      "response_time": {
          "max": 246,
          "avg": 126,
          "first": 246
      },
      "agent_ids": [
          "123"
      ],
      "agent_names": [
          "John"
      ],
      "triggered": false,
      "triggered_response": null,
      "missed": false,
      "tags": [ ],
      "department_id": 1,
      "department_name": "Billing Department",
      "unread": false,
      "history": [
          {
              "timestamp": "2014-10-09T05:28:35Z",
              "type": "chat.memberjoin",
              "name": "Visitor 123",
              "channel": "#supportchat:123"
          },
          {
              "name": "Visitor 123",
              "timestamp": "2014-10-09T05:28:35Z",
              "msg": "hello",
              "type": "chat.msg",
              "options": "",
              "channel": "#supportchat:123"
          },
          {
              "conversion": {
                  "attribution": {
                      "agent_name": "John",
                      "department_name": null,
                      "agent_id": 123,
                      "department_id": null,
                      "chat_timestamp": "2014-10-09T05:28:35Z"
                  },
                  "timestamp": "2014-10-09T05:40:35Z",
                  "goal_name": "test 1",
                  "goal_id": 1,
                  "id": "456"
              },
              "name": "Visitor 1490259935",
              "timestamp": "2014-10-09T05:35:35Z",
              "type": "chat.conversion",
              "channel": "#supportchat:123"
          },
          {
              "timestamp": "2014-10-09T05:46:47Z",
              "type": "chat.memberleave",
              "name": "Visitor 123",
              "channel": "#supportchat:123"
          }
      ],
      "conversions": [
        {
          "attribution": {
              "agent_name": "John",
              "department_name": null,
              "agent_id": 123,
              "department_id": null,
              "chat_timestamp": "2014-10-09T05:28:35Z"
          },
          "timestamp": "2014-10-09T05:40:35Z",
          "goal_name": "test 1",
          "goal_id": 1,
          "id": "456"
        }
      ],
      "rating": "good",
      "comment": "Great customer experience!",
      "webpath": [
        {
          'timestamp': '2014-06-20T08:34:17Z',
          'from': 'https://www.zendesk.com/',
          'to': 'https://www.zopim.com',
          'title': 'Dashboard - Visitor list - State'
        },
        {
          'timestamp': '2014-06-20T08:45:50Z',
          'from': 'https://www.zopim.com',
          'to': 'https://www.zopim.com/account/',
          'title': 'Zendesk Chat - Account Page'
        }
      ]
    },
    {
      "id": "123",
      "visitor": {
        "phone": "",
        "notes": "",
        "id": "1.12345",
        "name": "John",
        "email": "[email protected]"
      },
      "type": "chat",
      "started_by": "visitor",
      "session": {
        "city": "San Fransisco",
        "end_date": "2014-09-30T08:25:09Z",
        "ip": "49.204.60.93",
        "region": "California",
        "start_date": "2014-09-31T08:25:09Z",
        "platform": "Windows",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
        "country_code": "US",
        "country_name": "United States of America",
        "id": "12345",
        "browser": "Chrome"
      },
      "timestamp": "2014-09-30T08:25:09Z",
      "count": {
        "visitor": 2,
        "total": 2,
        "agent": 2
      },
      "duration": 1612,
      "response_time": {
        "max": 247,
        "avg": 100.0,
        "first": 56
      },
      "agent_names": ["Thomas"],
      "agent_ids": ["54321"],
      "triggered": false,
      "triggered_response": null,
      "unread": 0,
      "missed": false,
      "tags": [],
      "department_id": 1,
      "department_name": "Billing Department",
      "history": [{
            "timestamp": "2014-09-30T08:25:09Z",
            "type": "chat.memberjoin",
            "name": "John",
            "channel": "#supportchat:1-12345",
            "nick": "visitor:1-12345"
        }, {
            "name": "John",
            "timestamp": "2014-09-30T08:25:10Z",
            "nick": "visitor:1-12345",
            "type": "chat.msg",
            "msg": "The chat window is open by default for the customers. Can we have it minimized?",
            "options": "",
            "channel": "#supportchat:1-12345"
        }
      ],
      "webpath": [
        {
          'timestamp': '2014-06-20T08:34:17Z',
          'from': 'https://www.zendesk.com/',
          'to': 'https://www.zopim.com',
          'title': 'Dashboard - Visitor list - State'
        },
        {
          'timestamp': '2014-06-20T08:45:50Z',
          'from': 'https://www.zopim.com',
          'to': 'https://www.zopim.com/account/',
          'title': 'Zendesk Chat - Account Page'
        }
      ]
    }
  ]
  "count" : 2,
  "prev_url": "null",
  "next_url": "null"
}

Search Chats

GET /api/v2/chats/search?q={search_string}

Allows an account owner or administrator to search for chats.

Rate limit

The Search Chats endpoint returns a limit of 10,000 results per query, or 250 pages with 40 results per page. If you request a page past the limit (?page=251), a 400 error status is returned.

If you need to retrieve large datasets, Zendesk recommends serializing the search into smaller chunks by limiting results by timestamp range.

Searchable fields

You can query the following fields:

Field Description Field name
Agent Name agent_names
Visitor Name visitor_name
Visitor Email ID visitor_email
Timestamp timestamp
End Timestamp end_timestamp
Chat Types chat_type; one of offline_msg or chat
Rating rating; one of good or bad
Free Text Not applicable (default)

A combination of two or more queries is also supported.

Example queries

Make sure to url-encode the query string in your code.

Search Query Returns
agent_names:Tom AND visitor_name:Harry Returns chats between agent Tom and visitor Harry
type:chat AND chocolate Returns chats with the term chocolate
visitor_email:[email protected] AND timestamp:[2014-10-10 TO 2014-12-12] Returns chats with visitor with email ID [email protected] between 2014-10-10 and 2014-12-12
timestamp:[2014-10-16 TO *] AND chocolate Returns chats that started after 2014-10-16 with chocolate
end_timestamp:[2014-10-25 TO *] AND rating:good Returns chats that ended after 2014-10-25 with good as the chat rating
Allowed for
  • Owner
  • Administrator
Using cURL
 
curl "https://www.zopim.com/api/v2/chats/search" \
-G --data-urlencode "q=timestamp:[2016-02-02T16:00:00 TO *] AND rating:good" \
-v -u {email_address}:{password}
Example Response
 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "url": "https://scribe.zopim.com/api/v2/chats/123",
      "timestamp": "2014-10-15T16:31:25Z",
      "preview": "Hi there! How are you?",
      "type": "chat",
      "id": "123"
    }
  ],
  "count": 1,
  "prev_url": null,
  "next_url": null
}

Get Chat

GET /api/v2/chats/{chat_id}

Fetches information about a chat by ID.

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats/{chat_id} \
  -v -u {email_address}:{password}
Example Response
 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "visitor": {
    "phone": "",
    "notes": "",
    "id": "1.12345",
    "name": "John",
    "email": "[email protected]"
  },
  "type":"chat",
  "started_by": "visitor",
  "session": {
    "city": "San Fransisco",
    "end_date": "2014-09-30T08:25:09Z",
    "ip": "49.204.60.93",
    "region": "California",
    "start_date": "2014-09-31T08:25:09Z",
    "platform": "Windows",
    "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
    "country_code": "US",
    "country_name": "United States of America",
    "id": "12345",
    "browser": "Chrome"
  },
  "timestamp": "2014-09-30T08:25:09Z",
  "count": {
    "visitor": 2,
    "total": 2,
    "agent": 2
  },
  "duration": 1612,
  "response_time": {
    "max": 247,
    "avg": 100.0,
    "first": 56
  },
  "agent_names": ["Thomas"],
  "agent_ids": ["54321"],
  "triggered": false,
  "triggered_response": null,
  "unread": 0,
  "missed": 0,
  "tags": [],
  "department_id": 1,
  "department_name": "Billing Department",
  "history": [{
        "timestamp": "2014-09-30T08:25:09Z",
        "type": "chat.memberjoin",
        "name": "John",
        "channel": "#supportchat:1-12345",
        "nick": "visitor:1-12345"
    }, {
        "name": "John",
        "timestamp": "2014-09-30T08:25:09Z",
        "nick": "visitor:1-12345",
        "type": "chat.msg",
        "msg": "The chat window is open by default for the customers. Can we have it minimized?",
        "options": "",
        "channel": "#supportchat:1-12345"
    }, {
        "conversion": {
            "attribution": {
                "agent_name": "Thomas",
                "department_name": null,
                "agent_id": 54321,
                "department_id": null,
                "chat_timestamp": "2014-10-09T05:28:35Z"
            },
            "timestamp": "2014-10-09T05:40:35Z",
            "goal_name": "test 1",
            "goal_id": 1,
            "id": "456"
        },
        "name": "Visitor 1490259935",
        "timestamp": "2014-10-09T05:35:35Z",
        "type": "chat.conversion",
        "channel": "#supportchat:123"
    }
  ],
  "conversions": [{
      "attribution": {
        "agent_name": "Thomas",
        "department_name": null,
        "chat_id": "54321",
        "department_id": null,
        "chat_timestamp": "2014-10-09T05:28:35Z"
        "agent_id": 54321
      },
      "account_id": 2,
      "timestamp": 1490259974,
      "goal_name": "test 1",
      "goal_id": 1,
      "id": "456"
    },
    {
      "attribution": {
        "agent_name": "Thomas",
        "department_name": null,
        "chat_id": "123",
        "department_id": null,
        "chat_timestamp": "2014-10-09T05:28:35Z"
        "agent_id": 54321
      },
      "account_id": 2,
      "timestamp": "2014-10-09T05:35:35Z",
      "goal_name": "test 2",
      "goal_id": 2,
      "id": "567"
    }
  ],
  "webpath": [
    {
      'timestamp': '2014-06-20T08:34:17Z',
      'from': 'https://www.zendesk.com/',
      'to': 'https://www.zopim.com',
      'title': 'Dashboard - Visitor list - State'
    },
    {
      'timestamp': '2014-06-20T08:45:50Z',
      'from': 'https://www.zopim.com',
      'to': 'https://www.zopim.com/account/',
      'title': 'Zendesk Chat - Account Page'
    }
  ]
}

Get Bulk Chat

GET /api/v2/chats?ids={list_of_chat_id}

Fetches information about multiple chats. Accepts a comma-separated list of up to 50 chat ids.

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats?ids=100,110 \
  -v -u {email_address}:{password} \
Example Response
 
HTTP/1.1 200 OK
Content-Type: application/json

{
"count": 24,
"docs": {
    "100": {
        "agent_ids": [...],
        "agent_names": [...],
        "comment": "Hi there!",
        "count": {...},
        ...
    },
    "110": {
        "agent_ids": [...],
        "agent_names": [...],
        "comment": "Help me",
        "count": {...},
        ...
    },
    ...
}

Create Chat

POST /api/v2/chats

Lets an agent create an offline message.

In addition to a visitor, message, and type value, you must specify a session and a timestamp value for the new chat.

Note: The API only supports creating offline messages.

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats \
  -d '{
         "visitor": {
            "phone":"",
            "notes":"",
            "id":"1.12345",
            "name": "John",
            "email": "vis[email protected]"
         },
         "message":"Hi there!",
         "type":"offline_msg",
         "timestamp": 1444156010,
         "session": {
           "browser": "Safari",
           "city": "Orlando",
           "country_code": "US",
           "country_name": "United States",
           "end_date": "2014-10-09T05:46:47Z",
           "id": "141109.654464.1KhqS0Nw",
           "ip": "67.32.299.96",
           "platform": "Mac OS",
           "region": "Florida",
           "start_date": "2014-10-09T05:28:31Z",
           "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10) AppleWebKit/600.1.25 (KHTML, like Gecko) Version/8.0 Safari/600.1.25"
         }
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"
Example Response
 
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123",
  "visitor": {
    "phone": "",
    "notes": "",
    "id": "1.12345",
    "name": "John",
    "email": "[email protected]"
  },
  "type":"chat",
  "message":"Hi there!",
  "type":"offline_msg",
  "started_by": "visitor",
  ...
}

Update Chat

PUT /api/v2/chats/{chat_id}

Lets an agent update the data of a specific chat.

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats/{chat_id} \
  -d '{"visitor.name" : "Joe"}' \
  -v -u {email_address}:{password} \
  -X PUT -H "Content-Type: application/json"
Example Response
 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "visitor": {
    "phone": "",
    "notes": "",
    "id": "1.12345",
    "name": "Joe",
    "email": "[email protected]"
  },
  "type":"offline_msg",
  "started_by": "visitor",
  ...
}

Delete Chat

DELETE /api/v2/chats/{chat_id}

Allowed for
  • Owner
  • Administrator
Using cURL
 
curl https://www.zopim.com/api/v2/chats/{chat_id} \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status: 204 No Content