The intercom API reference.
Home//
REST API Reference
/- Conversation handling events
Conversation
Handling Event
Handling Event List
Teammate Reference
Add tag to a conversation
Remove tag from a conversation
List all conversations
Creates a conversation
Retrieve a conversation
Update a conversation
Delete a conversation
Search conversations
Reply to a conversation
Manage 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
Conversation handling eve...
Intercom API (Unstable)
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/
AI Content
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
SchemasOperations
Bodyapplication/json
The ID of the type of ticket you want to convert the conversation to
Example: "1234"
The attributes set on the ticket. When setting the default title and description attributes, the attribute keys that should be used are _default_title_ and _default_description_. When setting ticket type attributes of the list attribute type, the key should be the attribute name and the value of the attribute should be the list item id, obtainable by listing the ticket type. For example, if the ticket type has an attribute called priority of type list, the key should be priority and the value of the attribute should be the guid of the list item (e.g. de1825a0-0164-4070-8ca6-13e22462fa7e).
Example: {"_default_title_":"Found a bug","_default_description_":"The button is not working"}
- The production API serverhttps://api.intercom.io/conversations/{id}/convert
- The european API serverhttps://api.eu.intercom.io/conversations/{id}/convert
- The australian API serverhttps://api.au.intercom.io/conversations/{id}/convert
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/conversations/123/convert \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"ticket_type_id": "53"
}'successful
The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.
Example: "1390"
An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.
Example: {"_default_title_":"Found a bug","_default_description_":"The button's not working"}
A ticket type, used to define the data fields to be captured in a ticket.
The time the ticket was created as a UTC Unix timestamp.
Example: 1663597223
The last time the ticket was updated as a UTC Unix timestamp.
Example: 1663597260
The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.
Example: 1663597260
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.
Response
application/json
{ "type": "ticket", "id": "611", "ticket_id": "22", "ticket_attributes": {}, "ticket_state": { "type": "ticket_state", "id": "7493", "category": "submitted", "internal_label": "Submitted", "external_label": "Submitted" }, "ticket_type": { "type": "ticket_type", "id": "53", "name": "my-ticket-type-1", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id442_that_should_be_at_least_", "archived": false, "created_at": 1734537737, "updated_at": 1734537737, "is_internal": false, "ticket_type_attributes": { … }, "category": "Customer" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1734537732, "updated_at": 1734537737, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 2 }, "open": true, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "category": "Customer", "is_shared": true }
- The production API serverhttps://api.intercom.io/conversations/{conversation_id}/handling_events
- The european API serverhttps://api.eu.intercom.io/conversations/{conversation_id}/handling_events
- The australian API serverhttps://api.au.intercom.io/conversations/{conversation_id}/handling_events
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
https://api.intercom.io/conversations/123/handling_events \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'Response
application/json
{ "handling_events": [ { … }, { … } ] }
Custom Object Instances
Everything about your Custom Object instances.
Permission Requirements
From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.
SchemasOperations
Reporting Data Export
Everything about Reporting Data Export. See this article for details on using the data to generate various metrics.
Operations