The intercom API reference.
Home//
REST API Reference
/- Attach a contact to a conversation
Conversation List Item
Conversation
Add tag to a conversation
Remove tag from a conversation
List all conversations
Creates a conversation
Retrieve a conversation
Update a conversation
Search conversations
Reply to a conversation
Manage a conversation
Run Assignment Rules on a conversation
Detach a contact from a group conversation
Redact a conversation part
Convert a conversation to a ticket
Attach a contact to a con...
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
Deprecation of Run Assignment Rules
Run assignment rules is now deprecated in version 2.12 and future versions and will be permanently removed on December 31, 2026. After this date, any requests made to this endpoint will fail.
You can let a conversation be automatically assigned following assignment rules.
When using workflows
It is not possible to use this endpoint with Workflows.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/conversations/{id}/run_assignment_rules
- The european API serverhttps://api.eu.intercom.io/conversations/{id}/run_assignment_rules
- The australian API serverhttps://api.au.intercom.io/conversations/{id}/run_assignment_rules
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/conversations/123/run_assignment_rules \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.10'Assign a conversation using assignment rules
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": "529", "created_at": 1717021895, "updated_at": 1717021896, "waiting_since": null, "snoozed_until": null, "source": { "type": "conversation", "id": "403918352", "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": 1 } }
Request
You can add participants who are contacts to a conversation, on behalf of either another contact or an admin.
Contacts without an email
If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with role set to lead.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/conversations/{id}/customers
- The european API serverhttps://api.eu.intercom.io/conversations/{id}/customers
- The australian API serverhttps://api.au.intercom.io/conversations/{id}/customers
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/conversations/123/customers \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.10' \
-d '{
"admin_id": 991268026,
"customer": {
"intercom_user_id": "6657accd6abd0166b52ae296"
}
}'Attach a contact to a conversation
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
{ "customers": [ { … } ] }
Request
You can add participants who are contacts to a conversation, on behalf of either another contact or an admin.
Contacts without an email
If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with role set to lead.
Security
bearerAuth
- The production API serverhttps://api.intercom.io/conversations/{conversation_id}/customers/{contact_id}
- The european API serverhttps://api.eu.intercom.io/conversations/{conversation_id}/customers/{contact_id}
- The australian API serverhttps://api.au.intercom.io/conversations/{conversation_id}/customers/{contact_id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X DELETE \
https://api.intercom.io/conversations/123/customers/123 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.10' \
-d '{
"admin_id": 991268034,
"customer": {
"intercom_user_id": "6657acd36abd0166b52ae29a"
}
}'Detach a contact from a group conversation
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
{ "customers": [ { … } ] }