Conversation Part

Conversation List

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.

typestringrequired

Always conversation.list

Value"conversation.list"

Example: "conversation.list"

conversationsArray of objects(Conversation)required

The list of conversation objects

conversations[].typestring

Always conversation.

Value"conversation"

Example: "conversation"

conversations[].idstringrequired

The id representing the conversation.

Example: "1295"

conversations[].titlestring or nullrequired

The title given to the conversation.

Example: "Conversation Title"

conversations[].created_atinteger(date-time)required

The time the conversation was created.

Example: 1663597223

conversations[].updated_atinteger(date-time)required

The last time the conversation was updated.

Example: 1663597260

conversations[].waiting_sinceinteger or null(date-time)required

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.

Example: 1663597260

conversations[].snoozed_untilinteger or null(date-time)required

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. i.e. it will be in a snoozed state until this time.

Example: 1663597260

conversations[].openbooleanrequired

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

Example: true

conversations[].statestringrequired

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

Enum"open""closed""snoozed"

Example: "open"

conversations[].readbooleanrequired

Indicates whether a conversation has been read.

Example: true

conversations[].prioritystring

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

Enum"priority""not_priority"

Example: "priority"

conversations[].admin_assignee_idinteger or nullrequired

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

Example: 0

conversations[].team_assignee_idstring or nullrequired

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

Example: "5017691"

conversations[].tagsobject(Tags)

A list of tags objects associated with a conversation

conversations[].conversation_ratingobject(Conversation Rating)

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

conversations[].sourceobject(Conversation source)required

The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.

conversations[].source.typestringrequired

This includes conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp.

Enum"conversation""email""facebook""instagram""phone_call""phone_switch""push""sms""twitter""whatsapp"

Example: "conversation"

conversations[].source.idstringrequired

The id representing the message.

Example: "3"

conversations[].source.delivered_asstringrequired

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

Example: "operator_initiated"

conversations[].source.subjectstringrequired

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

Example: ""

conversations[].source.bodystring

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

Example: "<p>Hey there!</p>"

conversations[].source.authorobject(Conversation part author)required

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.

conversations[].source.author.typestringrequired

The type of the author

Example: "admin"

conversations[].source.author.idstringrequired

The id of the author

Example: "274"

conversations[].source.author.namestringrequired

The name of the author

Example: "Operator"

conversations[].source.author.emailstring(email)required

The email of the author

Example: "operator+abcd1234@intercom.io"

conversations[].source.attachmentsArray of objects(Part attachment)

A list of attachments for the part.

conversations[].source.urlstring or null

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

Example: null

conversations[].source.redactedbooleanrequired

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

Example: false

conversations[].contactsobject(Contacts)required

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.

conversations[].contacts.typestringrequired

Value"contact.list"

Example: "contact.list"

conversations[].contacts.contactsArray of objects(Contact Reference)required

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.

conversations[].contacts.contacts[].typestringrequired

always contact

Value"contact"

Example: "contact"

conversations[].contacts.contacts[].idstringrequired

The unique identifier for the contact which is given by Intercom.

Example: "5ba682d23d7cf92bef87bfd4"

conversations[].contacts.contacts[].external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example: "f3b87a2e09d514c6c2e79b9a"

conversations[].teammatesobject(Conversation teammates)required

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

conversations[].teammates.typestringrequired

The type of the object - admin.list.

Example: "admin.list"

conversations[].teammates.teammatesArray of objects(Reference)required

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

conversations[].teammates.teammates[].typestringrequired

Example: "contact"

conversations[].teammates.teammates[].idstring or null

Example: "1a2b3c"

conversations[].custom_attributesobject(Custom Attributes)required

An object containing the different custom attributes associated to the conversation as key-value pairs. For relationship attributes the value will be a list of custom object instance models.

conversations[].custom_attributes.property name*string or Custom Object Instance (object)additional property

Any of:

string

conversations[].first_contact_replyobject(First contact reply)

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

conversations[].sla_appliedobject(Applied SLA)

The SLA Applied object contains the details for which SLA has been applied to this conversation. Important: if there are any canceled sla_events for the conversation - meaning an SLA has been manually removed from a conversation, the sla_status will always be returned as null.

conversations[].statisticsobject(Conversation statistics)

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

conversations[].conversation_partsobject(Conversation Parts)

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.

conversations[].linked_objectsobject(Linked Objects)

An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.

conversations[].ai_agent_participatedboolean

Indicates whether the AI Agent participated in the conversation.

Example: true

conversations[].ai_agentobject(AI Agent)

Data related to AI Agent involvement in the conversation.

total_countintegerrequired

A count of the total number of objects.

Example: 12345

pagesobject(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

{
  "type": "conversation.list",
  "conversations": [
    { … }
  ],
  "total_count": 12345,
  "pages": {
    "type": "pages",
    "page": 1,
    "next": { … },
    "per_page": 2,
    "total_pages": 13
  }
}

Conversation Part

A Conversation Part represents a message in the conversation.

typestringrequired

Always conversation_part

Value"conversation_part"

Example: "conversation_part"

idstringrequired

The id representing the conversation part.

Example: "3"

part_typestringrequired

The type of conversation part.

Example: "comment"

bodystring or null

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

Example: "<p>Okay!</p>"

created_atinteger(date-time)required

The time the conversation part was created.

Example: 1663597223

updated_atinteger(date-time)

The last time the conversation part was updated.

Example: 1663597260

notified_atinteger(date-time)required

The time the user was notified with the conversation part.

Example: 1663597260

assigned_toobject(Reference)

reference to another object

authorobject(Conversation part author)required

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.

author.typestringrequired

The type of the author

Example: "admin"

author.idstringrequired

The id of the author

Example: "274"

author.namestringrequired

The name of the author

Example: "Operator"

author.emailstring(email)required

The email of the author

Example: "operator+abcd1234@intercom.io"

attachmentsArray of objects(Conversation part attachments)

A list of attachments for the part.

external_idstring or null

The external id of the conversation part

Example: "abcd1234"

redactedbooleanrequired

Whether or not the conversation part has been redacted.

Example: false

{
  "type": "conversation_part",
  "id": "3",
  "part_type": "comment",
  "body": "<p>Okay!</p>",
  "created_at": 1663597223,
  "updated_at": 1663597260,
  "notified_at": 1663597260,
  "assigned_to": {
    "type": "contact",
    "id": "1a2b3c"
  },
  "author": {
    "type": "admin",
    "id": "274",
    "name": "Operator",
    "email": "operator+abcd1234@intercom.io"
  },
  "attachments": [
    { … }
  ],
  "external_id": "abcd1234",
  "redacted": false
}

Conversation part author

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.

typestringrequired

The type of the author

Example: "admin"

idstringrequired

The id of the author

Example: "274"

namestringrequired

The name of the author

Example: "Operator"

emailstring(email)required

The email of the author

Example: "operator+abcd1234@intercom.io"

{
  "type": "admin",
  "id": "274",
  "name": "Operator",
  "email": "operator+abcd1234@intercom.io"
}

Intercom API (2.11)

Admins

Articles

Companies

Contacts

Conversations

Data Attributes

Data Events

Data Export

Help Center

Messages

News

Notes

Segments

Subscription Types

Switch

Tags

Teams

Ticket Type Attributes

Ticket Types

Tickets

Visitors

Models

Conversation List

Conversation Part

Conversation part author