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.

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.

Multiple recipients supported when creating message

The create message endpooint now supports multiple users in the to and cc field in the form of an array of recipient objects.

Similarly the bcc field has been added.

{
  "from": {
    "type": "admin",
    "id": "991267816"
  },
  "to": [
    {
      "type": "user",
      "id": "6762f2391bb69f9f2193bc19"
    },
    {
      "type": "lead",
      "id": "6762f23c1bb69f9f2193bc1b"
    },
    {
      "type": "user",
      "id": "6762f23d1bb69f9f2193bc1c"
    }
  ],
  "cc": [
    {
      "type": "user",
      "id": "6762f23e1bb69f9f2193bc1d"
    },
    {
      "type": "user",
      "id": "6762f23f1bb69f9f2193bc1e"
    }
  ],
  "bcc": [
    {
      "type": "user",
      "id": "6762f23e1bb69f9f2193bc2f"
    }
  ],
  "message_type": "conversation",
  "body": "heyy"
}

AI agent and AI answer attributes available in author

Within the author object of a conversation part we have added two new fields: is_ai_answer and from_ai_agent.

Use from_ai_agent to understand if the bot reply was sent from the AI agent, rather than from a workflow operator or other type of bot.

Use is_ai_answer to understand if the reply represented in the conversation part was generated by the AI agent.

Send Quick Replies via the API

Quick replies represent admin defined values that an end-user can select, most often represented in the UI as clickable buttons that display below a message. In the Reply to a conversation endpoint, admins can define and send a choice of quick reply options, and end-users can choose their reply and their response can be sent using the API.

The historical reply option choices can be viewed for a conversation part in the metadata of the conversation part.

For example, this is what the quick reply options look like in a quick_reply part type from a bot.

{
  "metadata": {
    "quick_reply_options": [
      {
        "uuid": "1448547007",
        "text": "oui",
        "translations": {
          "en": "yes",
          "fr": "oui"
        }
      },
      {
        "uuid": "1448547008",
        "text": "non",
        "translations": {
          "en": "no",
          "fr": "non"
        }
      }
    ]
  }
}

Once the contact replies, the metadata on the conversation part will capture their choice and display it like this:

metadata: { quick_reply_option_uuid: '1448547007' }

New conversation operator replied webhook topic

You can now access replies from Fin in conversations using a new part of the conversations webhook. This is only available in unstable but can be used with the Conversations API to fully access conversations between customers and Fin. See the webhook models for details on how to access the operator replies.

Away status reason list API

Starting in April 2025, custom away status reasons per workspace can be fetched using the Away Status Reasons API.

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.

new Internal Articles API endpoints

You can now create, update, delete, list and search internal articles from your knowledge base via API

New Custom Channel Events

You can now integrate your own platform as a custom Intercom channel, by notifying Intercom of events that happen in it (like a user opening a conversation in your platform, or sending a message through your platform). These API endpoints are part of the closed Beta for "Fin over API", towards allowing Fin to work everywhere.