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