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"
        }
    ],
    "assignee": {
        {
            "id": "814860",
            "type": "admin",
          	"name": "Mark Strong",
          	"email": "mk@acmeinc.org"
        }
    },
    "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

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).
assignee	Object	The admin or team assigned to the conversation. If it's unassigned then it will return `null`.
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.

Note

Please note that URLs for User uploaded images & files have a 30 minute expiration. Once the expiration has passed, the link will no longer be valid and result in a 404. This means that if a URL is copied, and then reused elsewhere, it will continue to work until the expiry threshold. A new URL can be generated by fetching the conversation data again.

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", or "cancelled".

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.