The intercom API reference.
Home//
REST API Reference
/- Retrieve a conversation
Conversation List Item
Conversation
Add tag to a conversation
Remove tag from a conversation
List all conversations
Creates a conversation
Update a conversation
Search conversations
Reply to a conversation
Manage a conversation
Run Assignment Rules on a conversation
Attach a contact to a conversation
Detach a contact from a group conversation
Redact a conversation part
Convert a conversation to a ticket
Retrieve a conversation
Intercom API (2.10)
Download OpenAPI description
Overview
URL
License
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/
Request
You can create a conversation that has been initiated by a contact (ie. user or lead).
Sending for visitors
You can also send a message from a visitor by specifying their user_id or id value in the from field, along with a type field value of contact. This visitor will be automatically converted to a contact with a lead role once the conversation is created.
This will return the Message model that has been created.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/conversations
- The european API serverhttps://api.eu.intercom.io/conversations
- The australian API serverhttps://api.au.intercom.io/conversations
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/conversations \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.10' \
-d '{
"from": {
"type": "user",
"id": "6657ac8a6abd0166b52ae266"
},
"body": "Hello there"
}'Response
application/json
{ "type": "user_message", "id": "403918318", "created_at": 1717021835, "body": "Hello there", "message_type": "inapp", "conversation_id": "483" }
Request
You can fetch the details of a single conversation.
This will return a single Conversation model with all its conversation parts.
Hard limit of 500 parts
The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts.
For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a paid feature.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/conversations/{id}
- The european API serverhttps://api.eu.intercom.io/conversations/{id}
- The australian API serverhttps://api.au.intercom.io/conversations/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
'https://api.intercom.io/conversations/123?display_as=plaintext' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.10'conversation found
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
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
If marked as priority, it will return priority or else not_priority.
Enum"priority""not_priority"
Example: "priority"
The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.
Example: 0
The id of the team assigned to the conversation. If it's not assigned to a team it will return null.
Example: "5017691"
The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
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.
The list of teammates who participated in the conversation (wrote at least one conversation part).
An object containing information on the first users message. For a contact initiated message this will represent the users original message.
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.
A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
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.
Response
application/json
{ "type": "conversation", "id": "487", "created_at": 1717021841, "updated_at": 1717021841, "waiting_since": null, "snoozed_until": null, "source": { "type": "conversation", "id": "403918322", "delivered_as": "admin_initiated", "subject": "", "body": "<p>this is the message body</p>", "author": { … }, "attachments": [], "url": null, "redacted": false }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "first_contact_reply": null, "admin_assignee_id": null, "team_assignee_id": null, "open": false, "state": "closed", "read": false, "tags": { "type": "tag.list", "tags": [] }, "priority": "not_priority", "sla_applied": null, "statistics": null, "conversation_rating": null, "teammates": null, "title": null, "topics": {}, "ticket": null, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "conversation_parts": { "type": "conversation_part.list", "conversation_parts": [], "total_count": 0 } }
- The production API serverhttps://api.intercom.io/conversations/{id}
- The european API serverhttps://api.eu.intercom.io/conversations/{id}
- The australian API serverhttps://api.au.intercom.io/conversations/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X PUT \
'https://api.intercom.io/conversations/123?display_as=plaintext' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.10' \
-d '{
"read": true
}'conversation found
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
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
If marked as priority, it will return priority or else not_priority.
Enum"priority""not_priority"
Example: "priority"
The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.
Example: 0
The id of the team assigned to the conversation. If it's not assigned to a team it will return null.
Example: "5017691"
The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
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.
The list of teammates who participated in the conversation (wrote at least one conversation part).
An object containing information on the first users message. For a contact initiated message this will represent the users original message.
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.
A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
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.
Response
application/json
{ "type": "conversation", "id": "491", "created_at": 1717021846, "updated_at": 1717021848, "waiting_since": null, "snoozed_until": null, "source": { "type": "conversation", "id": "403918326", "delivered_as": "admin_initiated", "subject": "", "body": "<p>this is the message body</p>", "author": { … }, "attachments": [], "url": null, "redacted": false }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "first_contact_reply": null, "admin_assignee_id": null, "team_assignee_id": null, "open": false, "state": "closed", "read": true, "tags": { "type": "tag.list", "tags": [] }, "priority": "not_priority", "sla_applied": null, "statistics": null, "conversation_rating": null, "teammates": null, "title": null, "topics": {}, "ticket": null, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "conversation_parts": { "type": "conversation_part.list", "conversation_parts": [ … ], "total_count": 2 } }