# 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](/docs/build-an-integration/learn-more/rest-apis/unversioned-changes) page.

There are [breaking changes](/docs/build-an-integration/learn-more/rest-apis/api-changelog#about-breaking-changes-in-the-intercom-api) in this version, which are detailed below.

## 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:**


```bash
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:**


```json
{
  "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](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/macros/).

## New WhatsApp Message status API

The [WhatsApp Message status API](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/whatsapp/getwhatsappmessagestatus) 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](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/Conversations/retrieveConversation/) will requires the "Read tickets" or "Write tickets" scope, as appropriate. When [listing conversations](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/Conversations/listConversations/) or [searching conversations](https://developers.intercom.com/docs/references/unstable/rest-api/api.intercom.io/Conversations/searchConversations/), 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.

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

We've extended the [Create a ticket](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/tickets/createticket) 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`