The messages that make up a side conversation are recorded as events.

JSON format

Side Conversation Events are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
actorobjecttruefalseThe participant who created the event. See Participants
created_atstringtruefalseThe time the side converation event was created
idstringtruefalseAutomatically assigned when the event is created
messageobjecttruefalseEvents of type "create" and "reply" have a message. See Messages
side_conversation_idstringtruefalseThe id of the side conversation the event belongs to
ticket_idintegertruefalseThe parent ticket id of the side conversation
typestringtruefalseThe type of event
updatesobjecttruefalseEvents of type "update" have fields here. See Updates
urlstringtruefalseThe API url of the side conversation
viastringtruefalseThe channel used when creating the event. See the Via object reference

Messages

The message object has the following properties:

NameTypeMandatoryComment
subjectstringnoThe subject of the message
preview_textstringnoA plain text string describing the message
bodystringnoThe plain text version of the body of the message
html_bodystringnoThe HTML version of the body of the message
fromobjectnoThe participant who sent the message. See Participants
toarrayyesThe list of participants the message was sent to. See Participants
external_idsobjectnoA key-value object where all values are strings. Used for metadata

Updates

The updates object has the following properties:

NameTypeComment
statestringThe state of the side conversation. Possible values: "open", "closed"
subjectstringThe subject of the side conversation

Example

{  "actor": {    "email": "[email protected]",    "name": "Johnny Agent",    "user_id": 35436  },  "created_at": "2018-11-20T16:58:36.453+00:00",  "id": "8566255a-ece5-11e8-857d-493066fa7b17",  "message": {    "body": "I was trying to print an email when the printer suddenly started burning",    "from": {      "email": "[email protected]",      "name": "Johnny Agent",      "user_id": 35436    },    "html_body": "I was trying to print an email when the printer suddenly started <strong>burning</strong>",    "preview_text": "I was trying to print an email when the printer suddenly",    "subject": "Help, my printer is on fire!",    "to": [      {        "email": "[email protected]",        "name": null,        "user_id": null      }    ],    "via": "support"  },  "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",  "type": "reply",  "via": "support"}

List Side Conversation Events

  • GET /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/events

Returns a list of side conversation events on the side conversation.

You can sideload side conversations.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
side_conversation_idstringPathtrueThe id of the side conversation
ticket_idintegerPathtrueThe id of the ticket

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/events.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	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://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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,  "events": [    {      "actor": {        "email": "[email protected]",        "name": "Johnny Agent",        "user_id": 35436      },      "created_at": "2018-11-20T16:58:36.453+00:00",      "id": "8566255a-ece5-11e8-857d-493066fa7b17",      "message": {        "body": "I was trying to print an email when the printer suddenly started burning",        "from": {          "email": "[email protected]",          "name": "Johnny Agent",          "user_id": 35436        },        "html_body": "I was trying to print an email when the printer suddenly started <strong>burning</strong>",        "preview_text": "I was trying to print an email when the printer suddenly",        "subject": "Help, my printer is on fire!",        "to": [          {            "email": "[email protected]",            "name": null,            "user_id": null          }        ],        "via": "support"      },      "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",      "type": "reply",      "via": "support"    }  ],  "next_page": null,  "previous_page": null}

Incremental Side Conversation Event Export

  • GET /api/v2/tickets/side_conversations/events?unix_time={unix_time}

Returns the side conversation events created since the start time. See start_time.

Allowed for

  • Admins

Parameters

NameTypeInRequiredDescription
unix_timeintegerQuerytrueA query start time for incremental exports

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1332034771 \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/tickets/side_conversations/events?unix_time=1383685952"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	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://support.zendesk.com/api/v2/tickets/side_conversations/events")		.newBuilder()		.addQueryParameter("unix_time", "1383685952");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/tickets/side_conversations/events',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'unix_time': '1383685952',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/tickets/side_conversations/events?unix_time=1383685952"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/tickets/side_conversations/events")uri.query = URI.encode_www_form("unix_time": "1383685952")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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,  "end_time": 1383685952,  "events": [    {      "actor": {        "email": "[email protected]",        "name": "Johnny Agent",        "user_id": 35436      },      "created_at": "2018-11-20T16:58:36.453+00:00",      "id": "8566255a-ece5-11e8-857d-493066fa7b17",      "message": {        "body": "I was trying to print an email when the printer suddenly started burning",        "from": {          "email": "[email protected]",          "name": "Johnny Agent",          "user_id": 35436        },        "html_body": "I was trying to print an email when the printer suddenly started <strong>burning</strong>",        "preview_text": "I was trying to print an email when the printer suddenly",        "subject": "Help, my printer is on fire!",        "to": [          {            "email": "[email protected]",            "name": null,            "user_id": null          }        ],        "via": "support"      },      "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",      "type": "reply",      "via": "support"    }  ],  "next_page": "https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1383685952"}