Changelog (v2.13)

For changes that have been updated across all version, see the Unversioned changes page.

New API Endpoints

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 by ID or by external ID

Get Contact by External ID

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.

Try Getting a Contact by External ID

Block contact API

You can now block a contact via the Block Contact API

Try Blocking a contact

Delete a conversation

You can now delete a conversation using the ID assigned by Intercom when the conversation was created.

Try Deleting a conversation

Delete a ticket

You can delete a ticket using the ID assigned by Intercom when the ticket was created.

Try Deleting a ticket

curl -i -X DELETE \
  'https://api.intercom.io/tickets/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Backwards Compatible Changes

Added ability to associate custom object instances with contacts / conversations

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.

You can now create associations between custom object instances and:

Additional fields in Conversations API

We added new fields to the response of the Retrieve a conversation endpoint.

Response and handling time metrics
- assigned_team_first_response_time
- assigned_team_first_response_time_in_office_hours
- handling_time
Email metadata (Only for conversation parts sent as emails.)
- email_message_metadata
Curent conversation state and workflow/action details
- state
- tags
- event_details
These fields are available when the conversation part has one of the following part_type values:
- conversation_attribute_updated_by_workflow
- conversation_attribute_updated_by_admin
- custom_action_started
- custom_action_finished
- operator_workflow_event

See the new fields when you retrieve a conversation

Added new field `app_package_code` to conversation_part and ticket_part response

We added a new field app_package_code to the conversation_part and ticket_part response objects. This field will return the code of the app package that created the conversation part or ticket part via API.

For conversations, when the part is not created via API, the app_package_code will be null.

For tickets, when the part is not created via API, the app_package_code field won't exist in the response.

Added ability to link to an existing ticket when creating a ticket

We've extended the Create a ticket request body with conversation_to_link_id. This adds the ability to link the created ticket to an existing one. Here are the valid ways of linking two tickets:

conversation | back-office ticket
customer tickets | non-shared back-office ticket
conversation | tracker ticket
customer ticket | tracker ticket

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: 2.13' \
  -d '{
    "ticket_type_id": 1,
    "contacts": [
      {
        "id": "663a200f0a29ce1b24741068"
      }
    ],
    "ticket_attributes": {
      "_default_title_": "help!",
      "_default_description_": "there is a problem"
    },
    "skip_notifications": true
  }'