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:

Name Type Read-only Mandatory Description
actor object true false The participant who created the event. See Participants
created_at string true false The time the side converation event was created
id string true false Automatically assigned when the event is created
message object true false Events of type "create" and "reply" have a message. See Messages
side_conversation_id string true false The id of the side conversation the event belongs to
ticket_id integer true false The parent ticket id of the side conversation
type string true false The type of event
updates object true false Events of type "update" have fields here. See Updates
url string true false The API url of the side conversation
via string true false The channel used when creating the event. See the Via object reference

Messages

The message object has the following properties:

Name Type Mandatory Comment
subject string no The subject of the message
preview_text string no A plain text string describing the message
body string no The plain text version of the body of the message
html_body string no The HTML version of the body of the message
from object no The participant who sent the message. See Participants
to array yes The list of participants the message was sent to. See Participants
external_ids object no A key-value object where all values are strings. Used for metadata

Updates

The updates object has the following properties:

Name Type Comment
state string The state of the side conversation. Possible values: "open", "closed"
subject string The 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

Name Type In Required Description
side_conversation_id string Path true The id of the side conversation
ticket_id integer Path true The 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}:{password}
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 "username:password"
	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();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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 "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/tickets/1/side_conversations/e9ad3991-35e8-445e-a8cc-3d56862cb1f7/events"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"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")request.basic_auth "username", "password"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

Name Type In Required Description
unix_time integer Query true A 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}:{password}
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 "username:password"
	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");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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 "username:password"  },  params: {    'unix_time': '1383685952',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/tickets/side_conversations/events?unix_time=1383685952"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"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")request.basic_auth "username", "password"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"}