DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

The conversation model

Example Conversation Object

{
    "type": "conversation",
    "id": "1911149811",
    "created_at": 1539897198,
    "updated_at": 1540393270,
    "source": {
        "attachments": [],
        "author": {
            "id": "5bc8f7421ae2d96695c18a",
            "type": "lead"
        },
        "body": "<p>Hi</p>",
        "delivered_as": "customer_initiated",
        "id": "269650473",
        "subject": "",
        "type": "conversation",
        "url": "https://intercom-survey-app.glitch.me/",
        "redacted": false
    },
    "contacts": [
        {
            "id": "5bc8f7ae2d96695c18a",
            "type": "lead"
        }
    ],
    "teammates": [
        {
            "id": "814860",
            "type": "admin"
        }
    ],
    "title": "Conversation Title",
    "admin_assignee_id": 814860,
    "team_assignee_id": null,
    "custom_attributes": {
      "issue_type": "Billing",
      "priority": "High"
    },
    "topics": {
        "type": "topic.list",
        "topics": [
            {
                "type": "topic"
                "name": "Example Topic 1",
                "id": 839
            }
        ],
        "total_count": 1
    },
    "open": true,
    "state": "open",
    "read": true,
    "waiting_since": 64654125776,
    "snoozed_until": null,
    "tags": {
        "tags": [],
        "type": "tag.list",
    },
    "first_contact_reply": {
        "created_at": 1539897198
        "type": "conversation",
        "url": "https://intercom-survey-app.glitch.me/"
    },
    "priority": "not_priority",
    "sla_applied": {
        "sla_name": "VIP customer <5m",
      "sla_status": "missed",
    },
    "conversation_rating": {
        "created_at": null,
        "contact": {
            "id": null,
            "type": null
        },
        "rating": null,
        "remark": null,
        "teammate": {
            "id": null,
            "type": null
        }
    },
    "statistics": {
      "time_to_assignment": 2310,
      "time_to_admin_reply": 2408,
      "time_to_first_close": 4915 ,
      "time_to_last_close": 5125,
      "median_time_to_reply": 321,
      "first_contact_reply_at": 1539897200,
      "first_assignment_at": 1539897200,
      "first_admin_reply_at": 1539897200,
      "first_close_at": 1539897200,
      "last_assignment_at": 1539897200,
      "last_assignment_admin_reply_at": 1539897200,
      "last_contact_reply_at": 1539897200,
      "last_admin_reply_at": 1539897200,
      "last_close_at": 1539897200,
      "last_closed_by": {
        "type": "admin",
        "id": "325432652",
        "name": "Tom Smith",
        "email": "[email protected]"
      },
      "count_reopens": 3,
      "count_assignments": 2,
      "count_conversation_parts": 67
    },
    "conversation_parts": {
        "conversation_parts": [
            {
                "assigned_to": null,
                "attachments": [],
                "author": {
                    "id": "815309",
                    "type": "bot"
                },
                "body": "<p>Test_App typically replies in a few hours.</p>",
                "created_at": 1539897200,
                "external_id": null,
                "id": "2202737122",
                "notified_at": 1539897200,
                "part_type": "comment",
                "type": "conversation_part",
                "updated_at": 1539897200,
                "redacted": false
            },
          #List of conversation parts...
        ],
        "total_count": 67,
        "type": "conversation_part.list"
    }    
}
{
   "type":"conversation",
   "id":"1122334455",
   "created_at":1567693209,
   "updated_at":1568367881,
   "waiting_since":1568367881,
   "snoozed_until":null,
   "admin_assignee_id": "814860",
   "team_assignee_id": null,
   "open":true,
   "state":"open",
   "read":true,
   "tags":{
      "type":"tag.list",
      "tags":[

      ]
   },
   "conversation_rating":{
      "rating":null,
      "remark":null,
      "created_at":null,
      "customer":{
         "type":null,
         "id":null
      },
      "teammate":{
         "type":null,
         "id":null
      }
   },
   "conversation_parts":{
      "type":"conversation_part.list",
      "conversation_parts":[
         {
            "type":"conversation_part",
            "id":"1223445555",
            "part_type":"comment",
            "body":"We've removed this part of the conversation to comply with Twitter's terms and conditions. You can view the complete conversation in Intercom.",
            "created_at":1567693273,
            "updated_at":1567693273,
            "notified_at":1567693273,
            "assigned_to":null,
             "author":{
               "type":"user",
               "id":"5310d8e7598c9a0b24000002",
               "name":"",
               "email":""
            },
            "attachments": [],
            "external_id":null
         },
      ],
      "total_count":1
   },
   "customer_first_reply":{
      "created_at":1567693209,
      "type":"twitter",
      "url":""
   },
   "conversation_message":{
      "type":"twitter",
      "id":"409820079",
      "delivered_as":"customer_initiated",
      "subject":"We've removed this part of the conversation to comply with Twitter's terms and conditions. You can view the complete conversation in Intercom.",
      "body":"We've removed this part of the conversation to comply with Twitter's terms and conditions. You can view the complete conversation in Intercom.",
      "author":{
         "type":"user",
         "id":"5310d8e7598c9a0b24000002",
         "name":"",
         "email":""
      },
      "attachments":[

      ],
      "url":""
   },
   "customers":[
      {
         "type":"user",
         "id":"5310d8e7598c9a0b24000002"
      }
   ],
   "user":{
      "type":"user",
      "id":"5310d8e7598c9a0b24000002"
   }
}

Conversations are how you can communicate with users in Intercom. They are created when a contact replies to an outbound message, or when one admin directly sends a message to a single contact.

Conversation Object

Key

Type

Description

type

String

Always conversation.

id

String

The id representing the conversation.

created_at

Timestamp

The time the conversation was created.

updated_at

Timestamp

The last time the conversation was updated.

source

Object

The Conversation Part that originated this conversation, which can be Contact, Admin, Campaign, Automated or Operator initiated.

contacts

List

The list of contacts (users or leads) involved in this conversation.
This will only contain one customer unless more were added via the group conversation feature.

teammates

List

The list of teammates who participated in the conversation (wrote at least one conversation part).

title

String

The title given to the conversation.

admin_assignee_id

Integer

The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.

team_assignee_id

String

The id of the team assigned to the conversation. If it's not assigned to a team it will return null.

custom_attributes

Object

An object containing the different custom attributes associated to the conversation as key-value pairs.

open

Boolean

Indicates whether a conversation is open (true) or closed (false).

state

String

Can be set to "open", "closed" or "snoozed".

read

Boolean

Indicates whether a conversation has been read.

waiting_since

Timestamp

The last time a Contact responded to an Admin.
In other words, the time a customer started waiting for a response. Set to null if last reply is from an Admin.

snoozed_until

Timestamp

If set this is the time in the future when this conversation will be marked as open.
i.e. it will be in a snoozed state until this time.

tags

List

A list of tags objects associated with the conversation.

first_contact_reply

Object

An object containing information on the first users message. For a contact initiated message this will represent the users original message.

priority

String

If marked as priority, it will return priority or else not_priority.

sla_applied

Object

The SLA Applied object contains the details for which SLA has been applied to this conversation.

conversation_rating

Object

The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.

statistics

Object

A Statistics object containing all information required for reporting, with timestamps and calculated metrics.

conversation_parts

List

A list of Conversation Part objects for each part message in the conversation. This is only returned when Retrieving a Conversation, and ignored when Listing all Conversations. There is a limit of 500 parts.

Source object

Attribute

Type

Description

type

String

This includes conversation, push, facebook, twitter and email.

id

String

The id representing the message.

delivered_as

String

Optional. The message subject.
For Twitter, this will show a generic message regarding why

subject

String

Optional. The message subject.
For Twitter, this will show a generic message regarding why the subject is obscured.

body

String

The message body, which may contain HTML.
For Twitter, this will show a generic message regarding why the body is obscured.

author

Object

The object who initiated the conversation, which can be a Contact, Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams.
For Twitter, this will be blank.

attachments

List

A list of attachments for the part.

url

String

The URL where the conversation was started.
For Twitter, Email, and Bots, this will be blank.

redacted

Boolean

Whether or not the source message has been redacted. Only applicable for contact initiated messages.

Contact Object

Attribute

Type

Description

type

String

This can be either a user or a lead.

id

String

The ID for the user or lead.

Teammate Object

Attribute

Type

Description

type

String

Currently this will always be of type admin. Conversations not rated will return null.

id

String

The ID of the Admin.

First Contact Reply Object

Attribute

Type

Description

type

String

Over which channel did the first reply occur. Options include conversation, push, facebook, twitter and email.

url

String

The URL where the first reply originated from.
For Twitter and Email replies, this will be blank.

created_at

Timestamp

The time the users messages was created. This is in unix timestamp format.

Conversation Rating Object

Attribute

Type

Description

rating

Integer

The rating, between 1 and 5, for the conversation.

remark

String

An optional field to add a remark to correspond to the number rating.

created_at

Timestamp

The time the rating was requested in the conversation being rated.

contact

Object

An object containing the ID and type of the Contact.

teammate

Object

An object containing the ID and type of the Intercom teammate associated with the conversation when it was rated.

SLA Object

Attribute

Type

Description

sla_name

String

The name of the SLA as given by the teammate when it was created.

sla_status

String

One of “hit”, ”missed”, “cancelled”, or "active".

Statistics Object

Attribute

Type

Description

time_to_assignment

Integer

Duration until last assignment before first admin reply. In seconds.

time_to_admin_reply

Integer

Duration until first admin reply. Subtracts out of business hours. In seconds.

time_to_first_close

Integer

Duration until conversation was closed first time. Subtracts out of business hours. In seconds.

time_to_last_close

Integer

Duration until conversation was closed last time. Subtracts out of business hours. In seconds.

median_time_to_reply

Integer

Median based on all admin replies after a contact reply. Subtracts out of business hours. In seconds.

first_contact_reply_at

Timestamp

Time of first text conversation part from a contact.

first_assignment_at

Timestamp

Time of first assignment after first_contact_reply_at.

first_admin_reply_at

Timestamp

Time of first admin reply after first_contact_reply_at.

first_close_at

Timestamp

Time of first close after first_contact_reply_at.

last_assignment_at

Timestamp

Time of last assignment after first_contact_reply_at.

last_assignment_admin_reply_at

Timestamp

Time of first admin reply since most recent assignment.

last_contact_reply_at

Timestamp

Time of the last conversation part from a contact.

last_admin_reply_at

Timestamp

Time of the last conversation part from an admin.

last_close_at

Timestamp

Time of the last conversation close.

last_closed_by

Object

The last admin who closed the conversation. Returns a reference to an Admin object.

count_reopens

Integer

Number of reopens after first_contact_reply_at.

count_assignments

Integer

Number of assignments after first_contact_reply_at.

count_conversations_parts

Integer

Total number of conversation parts.

Conversation Part Object

🚧

Conversation Parts are not returned when listing or searching for all conversations, only when retrieving a single conversation. There is also a limit of 500 parts.

Attribute

Type

Description

type

String

Always conversation_part.

id

String

The id representing the conversation part.

part_type

String

The type of conversation part.

body

String

The message body, which may contain HTML.
For Twitter, this will show a generic message regarding why the body is obscured.

created_at

Timestamp

The time the conversation part was created.

updated_at

Timestamp

The last time the conversation part was updated.

notified_at

Timestamp

The time the user was notified with the conversation part.

assigned_to

String

The id of the admin that was assigned the conversation by this conversation_part (null if there has been no change in assignment.)

author

String

The type of individual that sent the message (user, admin or bot) and their related id.
For Twitter, this will be blank.

attachments

List

A list of attachments for the part.

redacted

Boolean

Whether or not a conversation part has been redacted.

Conversation Part Types

Type

Description

comment

Standard reply from customer or admin to a conversation.

note

A note created by an admin on the conversation. A note will only be viewable as an admin.

note_and_reopen

Add a note and reopen the conversations in the one action.

assignment

An assignment of the conversation to an admin, or Nobody.

open

Identifies a conversation has been opened.

close

Identifies a conversation has been closed.

away_mode_assignment

Conversation has been assigned due to the admin being in away mode.

participant_added

A participant has been added to a group conversation.

participant_removed

A participant has been removed from a group conversation.

conversation_rating_changed

A conversation rating has been changed, not this can only occur before the rating has been submitted. Once it has been submitted it cannot be changed.

conversation_rating_remark_added

A conversation remark has been added to the conversation.

snoozed

A conversation has been snoozed.

unsnoozed

A conversation has been unsnoozed.

assign_and_unsnooze

Assign a conversation and unsnooze it in one action..

timer_unsnooze

Unsnooze a conversation after a set time.