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.

Block contact API

You can now block a contact via the Block Contact API

Delete a conversation

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

Delete a ticket

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

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

You can now create associations between custom object instances and:

• Contacts
• Conversations

Additional fields in Conversations API

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

1. Response and handling time metrics

   • assigned_team_first_response_time
   • assigned_team_first_response_time_in_office_hours
   • handling_time

2. Email metadata (Only for conversation parts sent as emails.)

   • email_message_metadata

3. 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

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.

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
  }'