Chats

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

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:

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
zendesk_ticket_id	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/"
    }
  ],
  "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

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.

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

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

Name	Type	In	Required	Description
chat_id	integer	Path	true	The 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 timestamp value for the new chat.

Note: The API only supports creating offline messages.

Allowed for

• Administrator

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/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 -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" -X POST

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/chats"
	method := "POST"
	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();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://subdomain.zendesk.com/api/v2/chat/chats',
  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"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats")
request = Net::HTTP::Post.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)

201 Created

// 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": [],
  "zendesk_ticket_id": null
}

Update Chat

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

Lets an agent update the data of a specific chat.

Allowed for

• Administrator

Parameters

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

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/chats/{chat_id} \
  -d '{"visitor.name" : "Joe"}' \
  -v -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" -X PUT

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/chats/1"
	method := "PUT"
	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();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  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(
	"PUT",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats/1")
request = Net::HTTP::Put.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": "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/"
    }
  ],
  "zendesk_ticket_id": 83
}

Delete Chat

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

Allowed for

• Administrator

Parameters

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

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/chats/{chat_id} \
  -v -H "Authorization: Bearer {token}" -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/chats/1"
	method := "DELETE"
	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("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  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(
	"DELETE",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://subdomain.zendesk.com/api/v2/chat/chats/1")
request = Net::HTTP::Delete.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)

204 No Content

// Status 204 No Content

null

Bulk Delete Chats

• DELETE /api/v2/chat/chats?ids={ids}

Bulk delete chats with given list of chat IDs.

Allowed for

• Administrator

Parameters

Name	Type	In	Required	Description
ids	string	Query	true	IDs of multiple chats to be deleted. Accepts a comma-separated list of up to 50 chat IDs.

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/chat/chats?ids={ids} \
  -v -H "Authorization: Bearer {token}" -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://subdomain.zendesk.com/api/v2/chat/chats?ids=100%2C110%2C111"
	method := "DELETE"
	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", "100,110,111");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://subdomain.zendesk.com/api/v2/chat/chats',
  headers: {
	'Content-Type': 'application/json',
  },
  params: {
    'ids': '100%2C110%2C111',
  },
};

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=100%2C110%2C111"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	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": "100,110,111")
request = Net::HTTP::Delete.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

{
  "failed": {
    "already_deleted": [
      "100"
    ],
    "invalid_id": [
      "111"
    ],
    "not_found": [
      "110"
    ]
  },
  "number_fail": 3,
  "number_success": 7
}