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.

The API supports offline messages and Support chats. There is a different JSON object representation for each chat type.

JSON Format for Offline Messages

Offline Messages are represented as JSON objects with the following properties:

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" or "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
zendeskticketid 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

Example

{  "id": "123",  "visitor": {    "id": "1.12345",    "phone": "",    "notes": "",    "email": "[email protected]",    "name": "John"  },  "type": "offline_msg",  "message": "Hi there!",  "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",  "department_id": 1,  "department_name": "Billing Department",  "unread": false,  "webpath": [ ]}

JSON Format

Support Chats are represented as JSON objects with the following properties:

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

Example

{  "agent_ids": [    "123"  ],  "agent_names": [    "John"  ],  "comment": "Great customer experience!",  "conversions": [    {      "attribution": {        "agent_id": 123,        "agent_name": "John",        "chat_timestamp": "2014-10-09T05:28:35Z",        "department_id": null,        "department_name": null      },      "goal_id": 1,      "goal_name": "test 1",      "id": "456",      "timestamp": "2014-10-09T05:40:35Z"    }  ],  "count": {    "agent": 0,    "total": 1,    "visitor": 1  },  "department_id": 1,  "department_name": "Billing Department",  "duration": 913,  "history": [    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.memberjoin"    },    {      "channel": "#supportchat:123",      "msg": "hello",      "name": "Visitor 123",      "options": "",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.msg"    },    {      "channel": "#supportchat:123",      "conversion": {        "attribution": {          "agent_id": 123,          "agent_name": "John",          "chat_timestamp": "2014-10-09T05:28:35Z",          "department_id": null,          "department_name": null        },        "goal_id": 1,        "goal_name": "test 1",        "id": "456",        "timestamp": "2014-10-09T05:40:35Z"      },      "name": "Visitor 1490259935",      "timestamp": "2014-10-09T05:35:35Z",      "type": "chat.conversion"    },    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:46:47Z",      "type": "chat.memberleave"    }  ],  "id": "123",  "missed": false,  "rating": "good",  "response_time": {    "avg": 126,    "first": 246,    "max": 246  },  "session": {    "browser": "Safari",    "city": "Orlando",    "country_code": "US",    "country_name": "United States",    "end_date": "2014-10-09T05:46:47Z",    "id": "141009.655464.1KhqS0Nw",    "ip": "67.23.229.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"  },  "started_by": "visitor",  "tags": [],  "timestamp": "2014-10-09T05:28:35Z",  "triggered": false,  "triggered_response": null,  "type": "chat",  "unread": false,  "visitor": {    "email": "[email protected]",    "id": "123",    "name": "Visitor 7",    "notes": "",    "phone": ""  },  "webpath": [    {      "from": "https://www.zendesk.com/",      "timestamp": "2014-06-20T08:34:17Z",      "title": "Dashboard - Visitor list - State",      "to": "https://www.zopim.com"    },    {      "from": "https://www.zopim.com",      "timestamp": "2014-06-20T08:45:50Z",      "title": "Zendesk Chat - Account Page",      "to": "https://www.zopim.com/account/"    }  ]}

List Chats

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

Lists all the chats for the account.

When a request is made with the ids filter, the response will include a docs map. It uses the chat ID as the key, and the chat properties are the values. Example:

{    "count": 24,    "docs": {        "100": {            "agent_ids": [],            "agent_names": [],            "comment": "Hi there!",            "count": {},            "<other chat 100 properties>": {}        },        "110": {            "agent_ids": [],            "agent_names": [],            "comment": "Help me",            "count": {},            "<other chat 110 properties>": {}        }    }  }

Allowed for

  • Owner
  • Administrator

Parameters

Name Type In Required Description
ids string Query false Fetches information about multiple chats. Accepts a comma-separated list of up to 50 chat ids.

Using curl

curl https://www.zopim.com/api/v2/chats \  -v -u {email_address}:{password}

Example Response

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

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": "[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

Status 201 Created
{  "department_id": 1,  "department_name": "Billing Department",  "id": "123",  "message": "Hi there!",  "session": {    "browser": "Safari",    "city": "Orlando",    "country_code": "US",    "country_name": "United States",    "end_date": "2014-10-09T05:46:47Z",    "id": "141009.655464.1KhqS0Nw",    "ip": "67.23.229.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"  },  "started_by": "visitor",  "timestamp": "2014-10-09T05:28:35Z",  "type": "offline_msg",  "unread": false,  "visitor": {    "email": "[email protected]",    "id": "1.12345",    "name": "John",    "notes": "",    "phone": ""  },  "webpath": []}

Search Chats

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

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

Parameters

Name Type In Required Description
q string Query true The query for this search. See Searchable fields for more information

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

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

Show Chat

  • GET /api/v2/chats/{chat_id}

Fetches information about a chat by ID.

Allowed for

  • Owner
  • Administrator

Parameters

Name Type In Required Description
chat_id integer Path true The ID of the chat

Using curl

curl https://www.zopim.com/api/v2/chats/{chat_id} \  -v -u {email_address}:{password}

Example Response

Status 200 OK
{  "agent_ids": [    "123"  ],  "agent_names": [    "John"  ],  "comment": "Great customer experience!",  "conversions": [    {      "attribution": {        "agent_id": 123,        "agent_name": "John",        "chat_timestamp": "2014-10-09T05:28:35Z",        "department_id": null,        "department_name": null      },      "goal_id": 1,      "goal_name": "test 1",      "id": "456",      "timestamp": "2014-10-09T05:40:35Z"    }  ],  "count": {    "agent": 0,    "total": 1,    "visitor": 1  },  "department_id": 1,  "department_name": "Billing Department",  "duration": 913,  "history": [    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.memberjoin"    },    {      "channel": "#supportchat:123",      "msg": "hello",      "name": "Visitor 123",      "options": "",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.msg"    },    {      "channel": "#supportchat:123",      "conversion": {        "attribution": {          "agent_id": 123,          "agent_name": "John",          "chat_timestamp": "2014-10-09T05:28:35Z",          "department_id": null,          "department_name": null        },        "goal_id": 1,        "goal_name": "test 1",        "id": "456",        "timestamp": "2014-10-09T05:40:35Z"      },      "name": "Visitor 1490259935",      "timestamp": "2014-10-09T05:35:35Z",      "type": "chat.conversion"    },    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:46:47Z",      "type": "chat.memberleave"    }  ],  "id": "123",  "missed": false,  "rating": "good",  "response_time": {    "avg": 126,    "first": 246,    "max": 246  },  "session": {    "browser": "Safari",    "city": "Orlando",    "country_code": "US",    "country_name": "United States",    "end_date": "2014-10-09T05:46:47Z",    "id": "141009.655464.1KhqS0Nw",    "ip": "67.23.229.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"  },  "started_by": "visitor",  "tags": [],  "timestamp": "2014-10-09T05:28:35Z",  "triggered": false,  "triggered_response": null,  "type": "chat",  "unread": false,  "visitor": {    "email": "[email protected]",    "id": "123",    "name": "Visitor 7",    "notes": "",    "phone": ""  },  "webpath": [    {      "from": "https://www.zendesk.com/",      "timestamp": "2014-06-20T08:34:17Z",      "title": "Dashboard - Visitor list - State",      "to": "https://www.zopim.com"    },    {      "from": "https://www.zopim.com",      "timestamp": "2014-06-20T08:45:50Z",      "title": "Zendesk Chat - Account Page",      "to": "https://www.zopim.com/account/"    }  ]}

Update Chat

  • PUT /api/v2/chats/{chat_id}

Lets an agent update the data of a specific chat.

Allowed for

  • Owner
  • Administrator

Parameters

Name Type In Required Description
chat_id integer Path true The ID of the chat

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

Status 200 OK
{  "agent_ids": [    "123"  ],  "agent_names": [    "John"  ],  "comment": "Great customer experience!",  "conversions": [    {      "attribution": {        "agent_id": 123,        "agent_name": "John",        "chat_timestamp": "2014-10-09T05:28:35Z",        "department_id": null,        "department_name": null      },      "goal_id": 1,      "goal_name": "test 1",      "id": "456",      "timestamp": "2014-10-09T05:40:35Z"    }  ],  "count": {    "agent": 0,    "total": 1,    "visitor": 1  },  "department_id": 1,  "department_name": "Billing Department",  "duration": 913,  "history": [    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.memberjoin"    },    {      "channel": "#supportchat:123",      "msg": "hello",      "name": "Visitor 123",      "options": "",      "timestamp": "2014-10-09T05:28:35Z",      "type": "chat.msg"    },    {      "channel": "#supportchat:123",      "conversion": {        "attribution": {          "agent_id": 123,          "agent_name": "John",          "chat_timestamp": "2014-10-09T05:28:35Z",          "department_id": null,          "department_name": null        },        "goal_id": 1,        "goal_name": "test 1",        "id": "456",        "timestamp": "2014-10-09T05:40:35Z"      },      "name": "Visitor 1490259935",      "timestamp": "2014-10-09T05:35:35Z",      "type": "chat.conversion"    },    {      "channel": "#supportchat:123",      "name": "Visitor 123",      "timestamp": "2014-10-09T05:46:47Z",      "type": "chat.memberleave"    }  ],  "id": "123",  "missed": false,  "rating": "good",  "response_time": {    "avg": 126,    "first": 246,    "max": 246  },  "session": {    "browser": "Safari",    "city": "Orlando",    "country_code": "US",    "country_name": "United States",    "end_date": "2014-10-09T05:46:47Z",    "id": "141009.655464.1KhqS0Nw",    "ip": "67.23.229.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"  },  "started_by": "visitor",  "tags": [],  "timestamp": "2014-10-09T05:28:35Z",  "triggered": false,  "triggered_response": null,  "type": "chat",  "unread": false,  "visitor": {    "email": "[email protected]",    "id": "123",    "name": "Joe",    "notes": "",    "phone": ""  },  "webpath": [    {      "from": "https://www.zendesk.com/",      "timestamp": "2014-06-20T08:34:17Z",      "title": "Dashboard - Visitor list - State",      "to": "https://www.zopim.com"    },    {      "from": "https://www.zopim.com",      "timestamp": "2014-06-20T08:45:50Z",      "title": "Zendesk Chat - Account Page",      "to": "https://www.zopim.com/account/"    }  ]}

Delete Chat

  • DELETE /api/v2/chats/{chat_id}

Allowed for

  • Owner
  • Administrator

Parameters

Name Type In Required Description
chat_id integer Path true The ID of the chat

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