Home
/
REST API Reference
/
conversations
/
The conversation model

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": "tom@example.com"
      },
      "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

KeyTypeDescription
typeStringAlways conversation.
idStringThe id representing the conversation.
created_atTimestampThe time the conversation was created.
updated_atTimestampThe last time the conversation was updated.
sourceObjectThe Conversation Part that originated this conversation, which can be Contact, Admin, Campaign, Automated or Operator initiated.
contactsListThe 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.
teammatesListThe list of teammates who participated in the conversation (wrote at least one conversation part).
titleStringThe title given to the conversation.
admin_assignee_idIntegerThe id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.
team_assignee_idStringThe id of the team assigned to the conversation. If it's not assigned to a team it will return null.
custom_attributesObjectAn object containing the different custom attributes associated to the conversation as key-value pairs.
openBooleanIndicates whether a conversation is open (true) or closed (false).
stateStringCan be set to "open", "closed" or "snoozed".
readBooleanIndicates whether a conversation has been read.
waiting_sinceTimestampThe 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_untilTimestampIf 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.
tagsListA list of tags objects associated with the conversation.
first_contact_replyObjectAn object containing information on the first users message. For a contact initiated message this will represent the users original message.
priorityStringIf marked as priority, it will return priority or else not_priority.
sla_appliedObjectThe SLA Applied object contains the details for which SLA has been applied to this conversation.
conversation_ratingObjectThe Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
statisticsObjectA Statistics object containing all information required for reporting, with timestamps and calculated metrics.
conversation_partsListA 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

AttributeTypeDescription
typeStringThis includes conversation, push, facebook, twitter and email.
idStringThe id representing the message.
delivered_asStringThe conversation's initiation type.
Possible values are customer_initiated, campaigns_initiated (legacy campaigns), operator_initiated (Custom bot), automated (Series and other outbounds with dynamic audience message) and admin_initiated (fixed audience message, ticket initiated by an admin, group email).
subjectStringOptional. The message subject.
For Twitter, this will show a generic message regarding why the subject is obscured.
bodyStringThe message body, which may contain HTML.
For Twitter, this will show a generic message regarding why the body is obscured.
authorObjectThe 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.
attachmentsListA list of attachments for the part.
urlStringThe URL where the conversation was started.
For Twitter, Email, and Bots, this will be blank.
redactedBooleanWhether or not the source message has been redacted. Only applicable for contact initiated messages.

Contact Object

AttributeTypeDescription
typeStringThis can be either a user or a lead.
idStringThe ID for the user or lead.

Teammate Object

AttributeTypeDescription
typeStringCurrently this will always be of type admin. Conversations not rated will return null.
idStringThe ID of the Admin.

First Contact Reply Object

AttributeTypeDescription
typeStringOver which channel did the first reply occur. Options include conversation, push, facebook, twitter and email.
urlStringThe URL where the first reply originated from.
For Twitter and Email replies, this will be blank.
created_atTimestampThe time the users messages was created. This is in unix timestamp format.

Conversation Rating Object

AttributeTypeDescription
ratingIntegerThe rating, between 1 and 5, for the conversation.
remarkStringAn optional field to add a remark to correspond to the number rating.
created_atTimestampThe time the rating was requested in the conversation being rated.
contactObjectAn object containing the ID and type of the Contact.
teammateObjectAn object containing the ID and type of the Intercom teammate associated with the conversation when it was rated.

SLA Object

AttributeTypeDescription
sla_nameStringThe name of the SLA as given by the teammate when it was created.
sla_statusStringOne of "hit", "missed", "cancelled", or "active".

Statistics Object

AttributeTypeDescription
time_to_assignmentIntegerDuration until last assignment before first admin reply. In seconds.
time_to_admin_replyIntegerDuration until first admin reply. Subtracts out of business hours. In seconds.
time_to_first_closeIntegerDuration until conversation was closed first time. Subtracts out of business hours. In seconds.
time_to_last_closeIntegerDuration until conversation was closed last time. Subtracts out of business hours. In seconds.
median_time_to_replyIntegerMedian based on all admin replies after a contact reply. Subtracts out of business hours. In seconds.
first_contact_reply_atTimestampTime of first text conversation part from a contact.
first_assignment_atTimestampTime of first assignment after first_contact_reply_at.
first_admin_reply_atTimestampTime of first admin reply after first_contact_reply_at.
first_close_atTimestampTime of first close after first_contact_reply_at.
last_assignment_atTimestampTime of last assignment after first_contact_reply_at.
last_assignment_admin_reply_atTimestampTime of first admin reply since most recent assignment.
last_contact_reply_atTimestampTime of the last conversation part from a contact.
last_admin_reply_atTimestampTime of the last conversation part from an admin.
last_close_atTimestampTime of the last conversation close.
last_closed_byObjectThe last admin who closed the conversation. Returns a reference to an Admin object.
count_reopensIntegerNumber of reopens after first_contact_reply_at.
count_assignmentsIntegerNumber of assignments after first_contact_reply_at.
count_conversations_partsIntegerTotal 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.

AttributeTypeDescription
typeStringAlways conversation_part.
idStringThe id representing the conversation part.
part_typeStringThe type of conversation part.
bodyStringThe message body, which may contain HTML.
For Twitter, this will show a generic message regarding why the body is obscured.
created_atTimestampThe time the conversation part was created.
updated_atTimestampThe last time the conversation part was updated.
notified_atTimestampThe time the user was notified with the conversation part.
assigned_toStringThe id of the admin that was assigned the conversation by this conversation_part (null if there has been no change in assignment.)
authorStringThe type of individual that sent the message (user, admin or bot) and their related id.
For Twitter, this will be blank.
attachmentsListA list of attachments for the part.
redactedBooleanWhether or not a conversation part has been redacted.

Conversation Part Types

TypeDescription
commentStandard reply from customer or admin to a conversation.
noteA note created by an admin on the conversation. A note will only be viewable as an admin.
note_and_reopenAdd a note and reopen the conversations in the one action.
assignmentAn assignment of the conversation to an admin, or Nobody.
openIdentifies a conversation has been opened.
closeIdentifies a conversation has been closed.
away_mode_assignmentConversation has been assigned due to the admin being in away mode.
participant_addedA participant has been added to a group conversation.
participant_removedA participant has been removed from a group conversation.
conversation_rating_changedA 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_addedA conversation remark has been added to the conversation.
snoozedA conversation has been snoozed.
unsnoozedA conversation has been unsnoozed.
assign_and_unsnoozeAssign a conversation and unsnooze it in one action..
timer_unsnoozeUnsnooze a conversation after a set time.
Previous page
Next page