Changelog (Unstable)
This version is not stable and everything within is subject to change. We recommend using this for test and staging environments, as opposed to within production.
For changes that have been updated across all versions, see the Unversioned changes page.
There are breaking changes in this version, which are detailed below.
Enforcement of ticket permissions on the Conversations API
Starting in early August 2024, accessing a ticket directly through the Conversations API will requires the "Read tickets" or "Write tickets" scope, as appropriate. When listing conversations or searching conversations, tickets will only be returned in the results if the caller has the "Read tickets" scope.
Previously, tickets were accessible through the Conversations API using only the "Read conversations" or "Write conversations" scope(s). Any apps relying on this behaviour will need to add the appropriate ticket permission, and have users reauthenticate.
Delete a Ticket
You can delete a ticket using the ID assigned by Intercom when the ticket is created.
Try Deleting a ticket
curl -i -X DELETE \
'https://api.intercom.io/tickets/{id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'
Skip notifications when creating, updating, or replying to a Ticket
By default, when a ticket is created, the contacts and teammates involved will receive notifications about the ticket in the Help Desk, Messenger, and email. There are cases where you may not want them to receive these notifications, for instance if you are importing tickets into your Intercom workspace.
With the skip_notifications
flag, you can now control whether the notification will be sent on a per-request basis. This will prevent you from having to turn off contacts notifications globally when making updates via the API. It will also prevent teammate notifications on desktop, mobile, and email.
This flag is available on the create a ticket, update a ticket, and reply to a ticket endpoints.
Here's an example of how it works. You can set it to true
to enable it, or leave it as false
by default.
curl -i -X POST \
https://api.intercom.io/tickets \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"ticket_type_id": 1,
"contacts": [
{
"id": "663a200f0a29ce1b24741068"
}
],
"ticket_attributes": {
"_default_title_": "help!",
"_default_description_": "there is a problem"
},
"skip_notifications": true
}'
New Get a Contact by External ID Endpoint
With the new get a contact by external_id endpoint, you can fetch the details of a single contact by using their external_id
. This ID is the unique identifier you set when you created the contact, so it's helpful if you don't easily have access to the Intercom provisioned ID.
Use the API by making a GET
request to https://api.intercom.io/contacts/find_by_external_id/{external_id}
.
Be sure to set your header to Intercom-Version: Unstable
with the request. If successful it will return a single contact, and a 404
error otherwise.
Try Getting a Contact by External ID
New Custom Object Instances API
We added a new API that allows you to:
- Create or Update a Custom Object instance
- Retrieve a Custom Object instance by ID or by external ID
- Delete a Custom Object instance
New Searchable Contact Attribute
We added formatted_phone
as a searchable attribute for contacts. This is the contact's phone number normalized to the E164 format.