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

Creating side conversations of different types

Update the participants array to create side conversations of different types (email, Slack, child tickets):

Side conversation type	Participant attribute(s)	Comment
email	user_id	Create an email side conversation using an existing user's id
email	email	Create an email side conversation to an external user's email
email	email, name	Create an email side conversation specifying both email and name of the external user
slack	slack_workspace_id, slack_channel_id	Create a Slack side conversation to a channel in a specific workspace
child ticket	support_group_id	Create a child ticket assigned to a support group
child ticket	support_group_id, support_agent_id	Create a child ticket assigned to a support agent belonging to a specific group

For email, you can pass in participants: [{ user_id: 123 }] or participants: [{ email: "[email protected]", name: "Johnny Agent"}].

For Slack, you must use slack_workspace_id and slack_channel_id for participants. Example: participants: [{ slack_workspace_id: "ABC", slack_channel_id: "DEF}].

To create a child ticket, pass in support_group_id to assign the ticket to a group, or support_group_id and support_agent_id to assign the ticket to an agent within a specific group. Example: participants: [{ support_group_id: 123, support_agent_id: 456 }]. You must add support_group_id for child tickets even when assigning the ticket to an agent.

You can't mix the different types of recipients for a given side conversation. Email can only use user_id, name, and email. Slack can only use slack_workspace_id and slack_user_id. Child tickets can only use support_group_id and 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"
    }
  ]
}