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
email 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": {}
  }
}