Side Conversations
Participant Objects
Both in side conversations and in side converation events we use the concept of participants. A participant can be a Support user, but it can also be a user identified only by email address. So in multiple places in the API we have participants with optional user ids.
The structure of a participant object is as follows:
Name | Type | Mandatory | Comment |
---|---|---|---|
user_id | integer | no | If the participant is an agent, this will be the ID of that agent |
name | string | no | The name of the participant |
string | no | The email address of the participant |
JSON Format
Side conversations are represented as JSON objects with the following keys:
Name | Type | Read-only | Mandatory | Comment |
---|---|---|---|---|
id | string | yes | no | Automatically assigned when the side conversation is created |
url | string | yes | no | The API url of the side conversation |
subject | string | no | no | The subject of the side conversation |
preview_text | string | yes | no | A plain text text describing the side conversation |
state | string | no | no | The state of the side conversation. Possible values: open , closed |
created_at | date | yes | no | The time the side converation was created |
updated_at | date | yes | no | The time of the last update of the side converation |
message_added_at | date | yes | no | The time of the last message on the side converation |
state_updated_at | date | yes | no | The time of the update of the state of the side converation |
participants | array | yes | no | An array of participants in the side converation. See Participant Objects |
Example
{
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17",
"subject": "Help, my printer is on fire!",
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"created_at": "2018-11-20T16:58:36.453+00:00",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"user_id": 35436,
"name": "Johnny Agent",
"email": "johnny@example.com"
},
{
"user_id": null,
"name": null,
"email": "bob@example.com"
}
]
}
List Side Conversations
GET /api/v2/tickets/{ticket_id}/side_conversations.json
Returns a list of side conversations on the given ticket.
You can sideload side conversation events.
Allowed for
- Agents
Show Side Conversation
GET /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}.json
Returns a side conversation.
You can sideload side conversation events.
Allowed for
- Agents
Create Side Conversation
POST /api/v2/tickets/{ticket_id}/side_conversations.json
Creates a new side conversation on the ticket.
Allowed For
- Agents
Request Body
Takes a Message object that specifies the initial message of the side conversation,
Example request
{
"message": {
"subject": "My printer is on fire!",
"body": "The smoke is very colorful.",
"to": [
{ "email": "someone@example.com" }
]
}
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/42/side_conversations.json \
-d '{"message": {"subject": "My printer is on fire!", "body": "The smoke is very colorful.", "to": [{"email": "someone@example.com"}]}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17
{
"side_conversation": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17",
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"subject": "My printer is on fire!",
"preview_text": "Thread preview",
"state": "open",
"participants": [
{
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
}, {
"user_id": null,
"name": null,
"email": "someone@example.com"
}
],
"created_at": "2017-10-27T17:56:16.678Z",
"updated_at": "2017-10-27T17:58:19.104Z",
"message_added_at": "2017-10-27T17:58:19.104Z",
"state_updated_at": "2017-10-27T17:56:16.678Z"
},
"event": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/events/9e19e100-abd5-11e8-b66e-af698c6d193c",
"id": "9e19e100-abd5-11e8-b66e-af698c6d193c",
"side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
"actor": {
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
},
"type": "create",
"created_at": "2017-10-27T17:56:16.678Z",
"via": "api",
"message": {
"subject": "My printer is on fire!",
"preview_text": "My printer is on fire!",
"from": {
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
},
"to": [
{
"user_id": null,
"name": null,
"email": "someone@example.com"
}
],
"body": "The smoke is very colorful.",
"html_body": "<div class=\"zd-comment\"><p>The smoke is very colorful.</p></div>"
},
"updates": {}
}
}
Update Side Conversation
PUT /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}.json
Updates the state and/or subject of the side conversation.
Allowed For
- Agents
Request Body
The PUT request takes one parameter, a side_conversation
object that lists the values to update. All properties are optional.
Name | Description |
---|---|
state | The new state of the side conversation. Possible values: open , closed |
subject | The subject of the side conversation. |
Example Body
{
"side_conversation": {
"state": "closed"
}
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17json \
-H "Content-Type: application/json" \
-d '{"side_conversation": {"state": "closed"}}' \
-v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK
{
"side_conversation": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17",
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"subject": "My printer is on fire!",
"preview_text": "Thread preview",
"state": "closed",
"participants": [
{
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
}, {
"user_id": null,
"name": null,
"email": "someone@example.com"
}
],
"created_at": "2017-10-27T17:56:16.678Z",
"updated_at": "2017-10-27T17:58:19.104Z",
"message_added_at": "2017-10-27T17:58:19.104Z",
"state_updated_at": "2017-10-27T17:56:16.678Z"
},
"event": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/events/9e19e100-abd5-11e8-b66e-af698c6d193c",
"id": "9e19e100-abd5-11e8-b66e-af698c6d193c",
"side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
"actor": {
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
},
"type": "update",
"created_at": "2017-10-27T17:56:16.678Z",
"via": "api",
"message": null,
"updates": {
"state": "closed"
}
}
}
Reply to a Side Conversation
POST /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/reply.json
Reply to a side conversation.
Allowed For
- Agents
Request Body
Takes a Message object that specifies the message to add to the side conversation,
Example request
{
"message": {
"subject": "My printer is on fire!",
"body": "The smoke is very colorful.",
"to": [
{ "email": "someone@example.com" }
]
}
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/reply.json \ \
-d '{"message": {"subject": "My printer is on fire!", "body": "The smoke is very colorful.", "to": [{"email": "someone@example.com"}]}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status: 200 OK
{
"side_conversation": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17",
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"subject": "My printer is on fire!",
"preview_text": "Thread preview",
"state": "open",
"participants": [
{
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
}, {
"user_id": null,
"name": null,
"email": "someone@example.com"
}
],
"created_at": "2017-10-27T17:56:16.678Z",
"updated_at": "2017-10-27T17:58:19.104Z",
"message_added_at": "2017-10-27T17:58:19.104Z",
"state_updated_at": "2017-10-27T17:56:16.678Z"
},
"event": {
"url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/events/9e19e100-abd5-11e8-b66e-af698c6d193c",
"id": "9e19e100-abd5-11e8-b66e-af698c6d193c",
"side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
"actor": {
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
},
"type": "reply",
"created_at": "2017-10-27T17:56:16.678Z",
"via": "api",
"message": {
"subject": "My printer is on fire!",
"preview_text": "My printer is on fire!",
"from": {
"user_id": 2,
"name": "Agent Sally",
"email": "sally@company.com"
},
"to": [
{
"user_id": null,
"name": null,
"email": "someone@example.com"
}
],
"body": "The smoke is very colorful.",
"html_body": "<div class=\"zd-comment\"><p>The smoke is very colorful.</p></div>"
},
"updates": {}
}
}