Support API

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