Side Conversations

Note: The Side Conversations API is in early access. To sign up and give feedback, see the Side Conversations API community post.

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).

JSON Format

Side conversations are represented as JSON objects with the following properties:

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
ticket_id	integer	yes	no	The id of the ticket associated with 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 conversation was created
updated_at	date	yes	no	The time of the last update of the side conversation
message_added_at	date	yes	no	The time of the last message on the side conversation
state_updated_at	date	yes	no	The time of the update of the state of the side conversation
participants	array	yes	no	An array of participants in the side conversation. See Participants
external_ids	object	no	no	A key-value store of metadata. All values must be strings

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

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": "[email protected]"
    },
    {
      "user_id": null,
      "name": null,
      "email": "[email protected]"
    }
  ],
  "external_ids": {
    "my_system_id": "abc-123-xyz"
  }
}

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 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" }
  },
  "external_ids": { "conversation-external": "zyx" }
}

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]"}]}' \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST

Example Response

Status: 201 Created

{
  "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": "[email protected]"
      }, {
         "user_id": null,
         "name": null,
         "email": "[email protected]"
      }
    ],
    "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",
    "external_ids": { "conversation-external": "zyx" }
  },
  "event": {
    "id":                   "9e19e100-abd5-11e8-b66e-af698c6d193c",
    "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
    "actor": {
      "user_id": 2,
      "name":    "Agent Sally",
      "email":   "[email protected]"
    },
    "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":   "[email protected]"
      },
      "to": [
        {
          "user_id": null,
          "name":    null,
          "email":   "[email protected]"
        }
      ],
      "body":          "The smoke is very colorful.",
      "html_body":    "<div class=\"zd-comment\"><p>The smoke is very colorful.</p></div>",
      "external_ids": { "message-external": "xyz" }
    },
    "updates": {}
  }
}

Update Side Conversation

PUT /api/v2/tickets/{ticket_id}/side_conversations/{side_conversation_id}.json

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"
  }
}

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

{
  "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":   "[email protected]"
      }, {
         "user_id": null,
         "name":    null,
         "email":   "[email protected]"
      }
    ],
    "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": {
    "id":                   "9e19e100-abd5-11e8-b66e-af698c6d193c",
    "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
    "actor": {
      "user_id": 2,
      "name":    "Agent Sally",
      "email":   "[email protected]"
    },
    "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/{id}/reply.json

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]" }
    ]
  }
}

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]"}]}' \
  -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":   "[email protected]"
      }, {
         "user_id": null,
         "name":    null,
         "email":   "[email protected]"
      }
    ],
    "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": {
    "id":                   "9e19e100-abd5-11e8-b66e-af698c6d193c",
    "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
    "actor": {
      "user_id": 2,
      "name":    "Agent Sally",
      "email":   "[email protected]"
    },
    "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":   "[email protected]"
      },
      "to": [
        {
          "user_id": null,
          "name":    null,
          "email":   "[email protected]"
        }
      ],
      "body":      "The smoke is very colorful.",
      "html_body": "<div class=\"zd-comment\"><p>The smoke is very colorful.</p></div>"
    },
    "updates": {}
  }
}