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.

This version of the API includes breaking changes. They are flagged below.

AI Agent Conversation Metadata Now Available in Conversations

You can now access additional metadata for conversations where an AI Agent was involved as part of the Conversations API.

When ai_agent_participated is true, data in the ai_agent object will be populated, including:

source_type: How the AI Agent involvement was triggered, like workflow or fin_preview
source_title: The title of the profile or workflow
last_answer_type: The type of the last answer delivered in the conversation, like ai_answer or custom_answer
resolution_state: The resolution outcome from AI Agent's participation in the conversation, such as confirmed_resolution or routed_to_team
rating: The Customer Satisfaction (CSAT) rating provided from 1-5. Note that you will need to enable Fin AI Agent CSAT in order to gather this rating
rating_remark: The user's rating as a comment, if they left one
content_sources: A list of content sources that were used by the AI Agent in the conversation

You can export and save this data for compliance and legal reasons, send it to your data warehouse, and use it in your own BI tools for further analysis and visualization.

Try it on the Conversations API get a conversation, list conversations, and search conversations pages or in your own terminal.

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.

Find the reference docs and try it out here.

New messenger_writable flag on Data Attributes

We added the flag messenger_writable to the Data Attribute model. It can be used to control if the Messenger can update a specific attribute: When it's set to false the attribute won't be writable by the Messenger Javascript API.

Breaking change

When you create a Data attribute, this flag is false by default on the Unstable and future versions. On versions 2.10 and earlier, it is true by default. If you need your attributes to be writable by the Messenger, pass messenger_writable: true when creating the attribute.

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.