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
| 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 | The 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). |
| 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. |