Changelog (Unstable)

Unstable API

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.

Breaking permission changes

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.