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:

NameTypeRead-onlyDescription
idstringyesThe ID of the chat
department_idintegeryesThe ID of the department to which the chat is directed
department_nameintegeryesThe name of the department to which the chat is directed
visitorobjectyesInformation about the visitor
typestringyesChat type. One of "offline_msg" or "chat"
sessionobjectyesInformation related to the chat session
timestamptimestampyesTimestamp for the chat
unreadbooleannoWhether the chat is unread
messagestringyesMessage of the chat
zendesk_ticket_idintegeryesThe 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": [ ],  "zendesk_ticket_id": 83}

JSON format

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

NameTypeRead-onlyMandatoryDescription
agent_idsarraytruefalseIDs of agents involved in the chat
agent_namesarraytruefalseNames of agents involved in the chat
commentstringfalsefalseThe customer comment on the chat
conversionsarraytruefalseLast 20 conversions (if any) attributed to the chat
countobjecttruefalseNumber of messages (each) by the visitor and the agent(s)
department_idintegertruefalseThe ID of the department to which the chat is directed
department_namestringtruefalseThe name of the department to which the chat is directed
durationintegertruefalseDuration of the chat
historyarraytruefalseChronological list of messages in the chat
idstringtruefalseThe ID of the chat
missedbooleantruefalseWhether the chat was missed or not
ratingstringfalsefalseThe customer satisfaction rating for the chat
response_timeobjecttruefalseStatistics about the response times in the chat, avg, max and first
sessionobjecttruefalseInformation related to the session of the session of the chat
started_bystringtruefalseWho started the chat. Can be one of "visitor", "agent", or "trigger"
tagsarrayfalsefalseTags associated with the chat
timestampstringtruefalseTimestamp for the chat
triggeredbooleantruefalseWhether the chat was a triggered chat or not
triggered_responsebooleantruefalseWhether the response was a triggered response or not
typestringtruefalseChat type. One of "offline_msg" or "chat"
unreadbooleanfalsefalseWhether the chat is unread
visitorobjecttruefalseInformation about the visitor
webpatharraytruefalseThe list of pages the customer navigated to during the chat
zendesk_ticket_idintegertruefalseThe 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/"    }  ],  "zendesk_ticket_id": 83}

List Chats

  • GET /api/v2/chat/chats
  • GET /api/v2/chat/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

  • Administrator

Parameters

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

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/chat/chats \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/chats?ids="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/chats")		.newBuilder()		.addQueryParameter("ids", "");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/chats',  headers: {	'Content-Type': 'application/json',  },  params: {    'ids': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://subdomain.zendesk.com/api/v2/chat/chats?ids="headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats")uri.query = URI.encode_www_form("ids": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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/"        }      ],      "zendesk_ticket_id": 83    },    {      "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/"        }      ],      "zendesk_ticket_id": 84    }  ],  "count": 2,  "next_url": "null",  "prev_url": "null"}

Search Chats

  • GET /api/v2/chat/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 DescriptionField name
Agent Nameagent_names
Visitor Namevisitor_name
Visitor Email IDvisitor_email
Timestamptimestamp
End Timestampend_timestamp
Chat Typeschat_type; one of offline_msg or chat
Ratingrating; one of good or bad
Free TextNot 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 QueryReturns
agent_names:Tom AND visitor_name:HarryReturns chats between agent Tom and visitor Harry
type:chat AND chocolateReturns 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 chocolateReturns chats that started after 2014-10-16 with chocolate
end_timestamp:[2014-10-25 TO *] AND rating:goodReturns chats that ended after 2014-10-25 with good as the chat rating

Allowed for

  • Owner
  • Administrator

Parameters

NameTypeInRequiredDescription
qstringQuerytrueThe query for this search. See Searchable fields for more information

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/chat/chats/search" \  -G --data-urlencode "q=timestamp:[2016-02-02T16:00:00 TO *] AND rating:good" \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/chats/search?q=timestamp%3A%5B2016-02-02T16%3A00%3A00+TO+%2A%5D+AND+rating%3Agood"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/chats/search")		.newBuilder()		.addQueryParameter("q", "timestamp:[2016-02-02T16:00:00 TO *] AND rating:good");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/chats/search',  headers: {	'Content-Type': 'application/json',  },  params: {    'q': 'timestamp%3A%5B2016-02-02T16%3A00%3A00+TO+%2A%5D+AND+rating%3Agood',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://subdomain.zendesk.com/api/v2/chat/chats/search?q=timestamp%3A%5B2016-02-02T16%3A00%3A00+TO+%2A%5D+AND+rating%3Agood"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats/search")uri.query = URI.encode_www_form("q": "timestamp:[2016-02-02T16:00:00 TO *] AND rating:good")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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/chat/chats/{chat_id}

Fetches information about a chat by ID.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
chat_idintegerPathtrueThe ID of the chat

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/chat/chats/{chat_id} \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://subdomain.zendesk.com/api/v2/chat/chats/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://subdomain.zendesk.com/api/v2/chat/chats/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://subdomain.zendesk.com/api/v2/chat/chats/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://subdomain.zendesk.com/api/v2/chat/chats/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats/1")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// 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/"    }  ],  "zendesk_ticket_id": 83}

Create Chat

  • POST /api/v2/chat/chats

Lets an agent create an offline message.

In addition to a visitor, message, and type value, you must specify a session and a