Side Conversation Events

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

The email or Slack messages that make up a side conversation are recorded as events.

JSON Format

Side conversation events are represented as JSON objects with the following properties:

Name Type Comment
id string Automatically assigned when the event is created
url string The API url of the side conversation
side_conversation_id string The ID of the side conversation the event belongs to
actor object The participant who created the event. See Participants
type string The type of event. Possible values: "create", "update", "reply", "add-entity"
via string The channel used when creating the event. Possible values: "support", "email", "api"
message object Events of type "create", and "reply" have a message. See Messages
updates object Events of type "update" have fields here. See Updates
created_at date The time the side converation event was created
ticket_id integer The ticket this side conversation was attached to with this event (if any)
Messages

The message object has the following properties:

Name Type Mandatory Comment
subject string no The subject of the message
preview_text string no A plain text string describing the message
body string no The plain text version of the body of the message
html_body string no The HTML version of the body of the message
from object no The participant who sent the message. See Participants
to array yes The list of participants the message was sent to. See Participants
external_ids object no A key-value object where all values are strings. Used for metadata
Updates

The updates object has the following properties:

Name Type Comment
state string The state of the side conversation. Possible values: "open", "closed"
subject string The subject of the side conversation
Example
{
  "id":                   "8566255a-ece5-11e8-857d-493066fa7b17",
  "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
  "created_at":           "2018-11-20T16:58:36.453+00:00"
  "type":                 "reply",
  "via":                  "support",
  "actor": {
    "user_id": 35436,
    "name":    "Johnny Agent",
    "email":   "[email protected]"
  },
  "message": {
    "subject":      "Help, my printer is on fire!",
    "preview_text": "I was trying to print an email when the printer suddenly",
    "body":         "I was trying to print an email when the printer suddenly started burning",
    "html_body":    "I was trying to print an email when the printer suddenly started <strong>burning</strong>",
    "from": {
      "user_id": 35436,
      "name":    "Johnny Agent",
      "email":   "[email protected]"
    },
    "to": [
      {
        "user_id": null,
        "name":    null,
        "email":   "[email protected]"
      }
    ],
    "via": "support"
  }
}

List Side Conversation Events

GET /api/v2/tickets/{ticket_id}/side_conversations/{id}/events.json

Returns a list of side conversation events on the side conversation.

You can sideload side conversations.

Allowed for
  • Agents

Incremental Side Conversation Event Export

GET /api/v2/tickets/side_conversations/events.json?start_time={unix_time}

Returns the side conversation events created since the start time. See Usage Notes.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1332034771 \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "end_time":  1383685952,
  "next_page": "https://{subdomain}.zendesk.com/api/v2/tickets/side_conversations/events.json?start_time=1383685952",
  "count":     1,
  "events": [
    {
      "id":                   "9e19e100-abd5-11e8-b66e-af698c6d193c",
      "side_conversation_id": "8566255a-ece5-11e8-857d-493066fa7b17",
      "created_at":           "2018-11-20T16:58:36.453+00:00"
      "type":                 "reply",
      ...
    }
  ]
}