Changelog (Unstable)

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.

Custom States for Tickets

Getting Ticket states

The Unstable API includes a new object within a Ticket object that provides additional details about a custom ticket state. This new object includes the unique ID for the custom state, the internal and external labels, and the category that the state is associated with.

  "ticket_state": {
    "id": "88",
    "category": "waiting_on_customer",
    "internal_label": "waiting on customer",
    "external_label": "waiting on customer"
  }

Ticket states with Ticket Types

Each state is associated with a Ticket Type, so you may now also see all of the ticket states available for a Ticket Type in the object.

"ticket_states": {
  "type": "list",
  "data": [
    {
      "id": "88",
      "category": "waiting_on_customer",
      "internal_label": "waiting on customer",
      "external_label": "waiting on customer"
    },
    {
      "id": "89",
      "category": "reopened",
      "internal_label": "re-opened",
      "external_label": "re-opened"
    }
  ]
}

Ticket states API

You can use the new Ticket states API to see all the Ticket states that exist in your workspace.

Updating Ticket states

You have the option of updating a Ticket state via the API using the ticket_state_id.

To update the ticket state you must supply a valid ticket_state_id that is associated with the Ticket Type that the ticket falls under. If you supply an invalid ID, you will get a 400 error:

{
  "type": "error.list",
  "request_id": "cde97e83-57ce-42bf-8d00-d8e34e9fd0ac",
  "errors": [
    {
      "code": "ticket_state_id_invalid",
      "message": "Ticket state id is not valid or is not associated with the ticket type"
    }
  ]
}

Try out updating a Ticket state using ticket_state_id.

Delete a Ticket

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

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 AI Content API options

You can now specify whether your content should be available for use by AI Agent or AI Copilot using the ai_agent_availability and ai_copilot_availability settings in the AI Content API when you create an external page or update an external page. Enable use by setting them to true or disable by setting to false.

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.

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 AI Content APIs

The AI Content APIs are a new addition to allow you to get content into Fin from private help centers that Fin wouldn't otherwise be able to access and learn from the content of. With the APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.

Feel free to submit your feedback on the AI Content APIs via Messenger, we’d love to hear from you!

Reply to conversations with Quick Replies

We added the ability to reply to conversations with Quick Replies. The Reply to a conversation endpoint now allows admins to reply to conversations with quick replies. When a user clicks on one of the given options, a comment conversation part will be created that includes metadata linking back to the quick reply option chosen.

New Searchable Contact Attribute

We added formatted_phone as a searchable attribute for contacts.