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