Skip to content
Home/
/
Changelog (Unstable)

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.

Ticket state change tracking

The Ticket object now includes a previous_ticket_state_id field that returns the ID of the ticket's previous state. This enables tracking ticket state transitions for reporting and compliance. The field returns null when no state change history exists.

Admin role now included in API responses

The admin object returned by GET /admins, GET /admins/{id}, GET /me, and PUT /admins/{id}/away now includes a role attribute when the admin has a role assigned. The role object contains the role id and name.

Example:

{
  "type": "admin",
  "id": "1295",
  "name": "Joe Example",
  "role": {
    "type": "role",
    "id": "456",
    "name": "Support Agent"
  }
}

Note: Admins with custom per-user permissions (no role assigned) will not have the role field.

Conversations API: display_as parameter behavior

The display_as query parameter in the Retrieve Conversation and List Conversation Parts endpoints now affects both the body and subject fields of conversation messages when set to plaintext. By default, both fields are returned in HTML format.

Conversation Webhook Serialization Alignment

Conversation webhook payloads now use the same serialization format as API responses:

  • Statistics date fields (first_contact_reply_at, first_assignment_at, first_admin_reply_at, first_close_at, last_assignment_at, last_assignment_admin_reply_at, last_contact_reply_at, last_admin_reply_at, last_close_at) now return Unix timestamp integers instead of ISO8601 strings.
  • body and subject fields now return plain text instead of HTML.

Data Connectors API

We've added a new Data Connectors API that lets you list your data connectors and view their execution history. Data connectors allow you to make HTTP requests to external APIs from Intercom workflows and AI agents.

New Endpoints:

  • GET /data_connectors - List all data connectors for your workspace
  • GET /data_connectors/{id}/execution_results - List execution results for a connector (paginated, filterable)
  • GET /data_connectors/{id}/execution_results/{id} - Retrieve a single execution result with request/response bodies

Key Features:

  • Cursor-based pagination: Navigate through execution results using the starting_after parameter
  • Filtering: Filter execution results by success, error_type, and time range (start_ts/end_ts)
  • Opt-in bodies: Use include_bodies=true to include request/response bodies in list results. The show endpoint always includes them.
  • Opt-in request URL: Use include_request_url=true to include the sanitised request URL

OAuth Scope Required: Read data connectors

For complete documentation and examples, see the Data Connectors API Reference.

New Data Connector execution webhook topic

You can now receive real-time notifications when Data Connector actions complete execution using the new data_connector.execution.completed webhook topic. This webhook provides operational visibility into connector execution outcomes, including success/failure status, HTTP response codes, error categorization, and execution timing. See the webhook models for details on how to subscribe to execution events.

Macros API

We've added a new Macros API that provides programmatic access to saved replies (macros) in Intercom. This API enables external applications to retrieve and display your team's pre-written responses, making it easier to integrate Intercom macros with third-party tools and workflows.

New Endpoints:

  • GET /macros - List all available macros with pagination
  • GET /macros/{id} - Retrieve a specific macro by ID

Key Features:

  • Cursor-based pagination: Navigate through large sets of macros efficiently using the starting_after parameter with Base64-encoded cursors
  • Smart placeholder transformation: Macros containing Intercom placeholders (e.g., {{user.name}}) are automatically transformed to XML-like attributes (<attribute key="user.name"/>) for easier parsing
  • Flexible filtering: Use the updated_since parameter to retrieve only recently modified macros
  • Team visibility controls: Respects macro visibility settings, showing only macros available to the authenticated user's teams
  • Channel availability: Each macro indicates where it can be used (inbox, messenger, or both)

OAuth Scope Required: READ_CONVERSATIONS

Use Cases:

  • Integration with training platforms like Solidroad for customer service simulations
  • Building custom macro management interfaces
  • Exporting macros for documentation or backup purposes
  • Analyzing macro usage and content across your organization

Example Request:

curl -X GET https://api.intercom.io/macros?per_page=10 \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Intercom-Version: @Unstable'

Example Response:

{
  "type": "list",
  "data": [
    {
      "type": "macro",
      "id": "123",
      "name": "Order Status Update",
      "body": "<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order is ready!</p>",
      "body_text": "Hi there, your order is ready!",
      "created_at": "2025-07-17T11:18:08.000Z",
      "updated_at": "2025-07-17T15:30:24.000Z",
      "visible_to": "everyone",
      "visible_to_team_ids": [],
      "available_on": ["inbox", "messenger"]
    }
  ],
  "pages": {
    "type": "pages",
    "per_page": 10,
    "next": {
      "starting_after": "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
    }
  }
}

Important Notes:

  • This API is currently available in the Unstable version only
  • Placeholders in macro bodies are transformed from Intercom format to XML-like attributes
  • The pagination cursor encodes [updated_at, id] for stable ordering
  • Maximum 150 macros can be retrieved per request

For complete documentation and more examples, see the Macros API Reference.

New WhatsApp Message status API

The WhatsApp Message status API is now available in the Unstable version. This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing information about delivery state and related message details.

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.

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.

< {label}
{label} >