Side Conversations
Side conversations allow agents to send an email to somebody outside the main conversation in a ticket and keep the email messages within the ticket. See Using side conversations in tickets in the Support Help Center.
Agents can also initiate a side conversation in Slack and keep all the messages in the ticket. See Using Slack in side conversations.
The email or Slack messages that make up a side conversation are recorded as events. See Side conversation events.
The Collaboration add-on is required for side conversations. See About add-ons (Professional and Enterprise).
Participants
A side conversation has participants. A participant can be a Support user with a user ID, but they can also be a user identified only by an email address. You don't need to specify a user ID for these users in the API.
The participant
object has the following properties:
Name | Type | Mandatory | Comment |
---|---|---|---|
user_id | integer | no | If the participant is an agent, the agent's user ID |
name | string | no | The name of the participant |
string | no | The email address of the participant | |
slack_workspace_id | string | no | If the participant is a Slack user or channel, the Slack workspace ID |
slack_user_id | string | no | If the participant is a Slack user, the Slack user id |
slack_channel_id | string | no | If the participant is a Slack channel, the Slack channel id |
support_group_id | string | no | If the participant is a Ticket, the support group id |
support_agent_id | string | no | If the participant is a Ticket, the support agent id |
JSON Format
Side Conversation are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | The time the side conversation was created |
external_ids | object | false | false | A key-value store of metadata. All values must be strings |
id | string | true | false | Automatically assigned when the side conversation is created |
message_added_at | string | true | false | The time of the last message on the side conversation |
participants | array | true | false | An array of participants in the side conversation. See Participants |
preview_text | string | true | false | A plain text text describing the side conversation |
state | string | false | false | The state of the side conversation |
state_updated_at | string | true | false | The time of the update of the state of the side conversation |
subject | string | false | false | The subject of the side conversation |
updated_at | string | true | false | The time of the last update of the side conversation |
url | string | true | false | The API url of the side conversation |
Example
{
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
}
List Side Conversations
GET /api/v2/tickets/{ticket_id}/side_conversations
Returns a list of side conversations on the given ticket.
You can sideload side conversation events.
Allowed for
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/side_conversations.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": 1,
"next_page": null,
"previous_page": null,
"side_conversations": [
{
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
}
]
}
Create Side Conversation
POST /api/v2/tickets/{ticket_id}/side_conversations
Creates a side conversation on the ticket.
Allowed for
- Agents
Request Body
Takes a message
object that specifies the initial message of the side conversation. See Messages.
Example:
{
"message": {
"subject": "My printer is on fire!",
"body": "The smoke is very colorful.",
"to": [
{ "email": "[email protected]" }
],
"external_ids": { "message-external": "xyz" },
"attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]
},
"external_ids": { "conversation-external": "zyx" }
}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
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": "[email protected]"}], "attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status 201 Created
{
"event": {
"actor": {
"email": "[email protected]",
"name": "Agent Sally",
"user_id": 2
},
"created_at": "2017-10-27T17:56:16.678Z",
"id": "9e19e100-abd5-11e8-b66e-af698c6d193c",
"message": {
"attachments": [
{
"content_type": "image/png",
"content_url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/attachments/s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d/download/image.png",
"file_name": "image.png",
"height": 214,
"id": "s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d",
"inline": false,
"size": 50645,
"width": 406
}
],
"body": "The smoke is very colorful.",
"external_ids": {
"message-external": "xyz"
},
"from": {
"email": "[email protected]",
"name": "Agent Sally",
"user_id": 2
},
"html_body": "\u003cdiv class=\"zd-comment\"\u003e\u003cp\u003eThe smoke is very colorful.\u003c/p\u003e\u003c/div\u003e",
"preview_text": "My printer is on fire!",
"subject": "My printer is on fire!",
"to": [
{
"email": "[email protected]",
"name": null,
"user_id": null
}
]
},
"side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
"type": "create",
"via": "api"
},
"side_conversation": {
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
},
"updates": {}
}
Show Side Conversation
GET /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}
Returns a side conversation.
You can sideload side conversation events.
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 |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/side_conversation/{side_conversation_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
}
Update Side Conversation
PUT /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}
Updates the state or subject of the side conversation.
Allowed for
- Agents
Request Body
The 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:
{
"side_conversation": {
"state": "closed"
}
}
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 |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17.json \
-d '{"side_conversation": {"state": "closed"}}' \
-H "Content-Type: application/json" \
-v -u {email_address}:{password} -X PUT
Example Response
Status 200 OK
{
"event": {
"actor": {
"email": "[email protected]",
"name": "Agent Sally",
"user_id": 2
},
"created_at": "2017-10-27T17:56:16.678Z",
"id": "9e19e100-abd5-11e8-b66e-af698c6d193c",
"message": {
"attachments": [
{
"content_type": "image/png",
"content_url": "http://www.example.com/api/v2/tickets/42/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17/attachments/s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d/download/image.png",
"file_name": "image.png",
"height": 214,
"id": "s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d",
"inline": false,
"size": 50645,
"width": 406
}
],
"body": "The smoke is very colorful.",
"external_ids": {
"message-external": "xyz"
},
"from": {
"email": "[email protected]",
"name": "Agent Sally",
"user_id": 2
},
"html_body": "\u003cdiv class=\"zd-comment\"\u003e\u003cp\u003eThe smoke is very colorful.\u003c/p\u003e\u003c/div\u003e",
"preview_text": "My printer is on fire!",
"subject": "My printer is on fire!",
"to": [
{
"email": "[email protected]",
"name": null,
"user_id": null
}
]
},
"side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
"type": "create",
"via": "api"
},
"side_conversation": {
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
},
"updates": {}
}
Reply to a Side Conversation
POST /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}/reply
Replies to a side conversation.
Allowed For
- Agents
Request Body
Takes a message
object that specifies the message to add to the side conversation. See Messages.
Example:
{
"message": {
"subject": "My printer is on fire!",
"body": "The smoke is very colorful.",
"to": [
{ "email": "[email protected]" }
]
}
}
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 |
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": "[email protected]"}], "attachment_ids": ["s3-d2a3111e-26d9-4e1c-88b4-cf7c0649d81d"]}' \
-H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status 200 OK
{
"count": 1,
"next_page": null,
"previous_page": null,
"side_conversations": [
{
"created_at": "2018-11-20T16:58:36.453+00:00",
"external_ids": {
"my_system_id": "abc-123-xyz"
},
"id": "8566255a-ece5-11e8-857d-493066fa7b17",
"message_added_at": "2018-11-20T16:58:36.453+00:00",
"participants": [
{
"email": "[email protected]",
"name": "Johnny Agent",
"user_id": 35436
},
{
"email": "[email protected]",
"name": null,
"user_id": null
}
],
"preview_text": "I was trying to print an email when the printer suddenly started burning",
"state": "open",
"state_updated_at": "2018-11-20T16:58:36.453+00:00",
"subject": "Help, my printer is on fire!",
"updated_at": "2018-11-20T16:58:36.453+00:00",
"url": "https://company.zendesk.com/api/v2/tickets/1/side_conversations/8566255a-ece5-11e8-857d-493066fa7b17"
}
]
}