Unversioned Changes

Some changes may need to be made across multiple versions and therefore are not considered to be released under any one version. You can find details of those changes here.

May 2024

AI Agent metadata in the Conversations API

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.

Define your own created at values in Conversations

When you create or reply to a conversation via the API, you now have the option to define your own created_at timestamps.

This is especially useful if you are importing conversations data from another source. Try it out using the Create a Conversation or Reply to a Conversation endpoints.

Add a company ID when you create a Ticket

Now when you create a Ticket, you can add the company_id that should be associated with the Ticket.

This is especially useful if you are importing conversations data from another source or if you need to retroactively add a company that the contacts on the ticket are associated with. Try it out using the Create a Ticket endpoint.

February 2024

Ticket States

Retrieving custom ticket states is available in versions 2.9, 2.10, 2.11 and Unstable versions of the Tickets API.

Two states have been added:

• ticket_state_internal_label: The state the ticket is currently in, in a human readable form. This is only visible within Intercom to teammates.
• ticket_state_external_label: The state the ticket is currently in, in a human readable form. This is visible to customers and can be viewed in the Messenger, Email, and Tickets portal.

Email Domains

The email_domain attribute has been added to the Contacts object in versions 2.0 and above.

April 2023

❗️Conversation Part IDs are not unique across all workspaces

As flagged in a previous update, we're making changes to our databases and models, and as a result, the id of a conversation_part will no longer be unique across all workspaces. We're continuing to make this change for other models, and we urge you to make the change for all identifiers which don't consider the workspace_id/app_id.

Previous updates

Supported HTML in Articles

From now on, additive changes to the HTML content returned by the Articles model will not be considered a breaking change. We will not be introducing new API versions when adding new supported HTML elements or attributes.

Removing element support or changing its shape in a way that causes previously supported HTML to become unsupported will still constitute a breaking change, and a new API version will be introduced in such cases.

We encourage all API consumers reading the contents of the Articles response to handle any valid HTML in the article body, not just the subset defined in the supported HTML specification. This will ensure your code is resilient in handling any new HTML elements or attributes we may support in the future.

❗️Listed Articles no longer return statistics

Articles which have been listed will no longer return a statistics object. In order to get these statistics, you will now have to take the id of the article you want to fetch the statistics object for, and retrieve the article individually.

Tables and Horizontal Rules are supported as Article HTML content

Articles now support both Tables and Horizontal rules. This will mean they will show in the Articles model, and can be added within the body of an Article when creating or updating these using the valid HTML. The Articles endpoint is available from V2.1 upwards.

Text component headers are bold for Messenger Canvas Kit apps

When a Text component which has a style of header is now rendered in a Messenger Canvas Kit app on web, the text will automatically be bold without need for markdown. This is in an effort to better style the text based on its given purpose, and makes for greater content accessibility.

❗️Obfuscating Twitter data within Conversation objects

We've been informed by Twitter that changes to their API policies mean we're no longer compliant. As a result, we've obfuscated several fields for conversations received from Twitter. This affects all versions of the API for the following models:

• Conversation Message Object
• Customer First Reply Object
• Conversation Part Object

❗️IDs are not unique across all workspaces

To improve performance, we're making changes to our databases and models, and as a result, id will no longer be unique across all workspaces.

This means that the only unique identifier you should use is the workspace_id/app_id. If you've mapped any data to id's other than the workspace_id/app_id, then you should ensure that you are providing the workspace_id/app_id alongside, or in place of, other id's.

We made the change for conversation identifiers — meaning the id of a conversation will only be unique to a given workspace. We plan to do the same for the id of a conversation_part some time in the future. We are also likely to apply this across several models in the future so we urge you to make the change for all identifiers which don't consider the workspace_id/app_id.