> This page is for version Generative (default).
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Changelog

## New End User profile fields

We have added two new optional fields to the [End User profile object](/generative/reference/end-users/overview):

* `avatar`: A URL to the end user's avatar image
* `display_name`: The end user's display name

## New chat window events in Embed2

We've added new events to the [`subscribeEvent`](/reference/embed2-reference#subscribeevent) action in Embed2 to help you better track user interactions within the chat window:

| Event key           | Trigger                                         | Payload                                            |
| :------------------ | :---------------------------------------------- | :------------------------------------------------- |
| `ada:minimize_chat` | Triggered when a user minimizes the chat window | `{ conversation_id: string, is_engaged: boolean }` |
| `ada:close_chat`    | Triggered when a user closes the chat window    | `{ conversation_id: string, is_engaged: boolean }` |

If you're using the Embed2 script, these events are immediately available. For the [NPM package](https://www.npmjs.com/package/@ada-support/embed2), update to the latest version (1.9.0) to start using them.

## BCP 47 support in article upserts

The `language` field on the article object in the upsert API now supports BCP 47 language tags (e.g., `en-CA`, `fr-FR`). The previously supported `locale` field is deprecated but still accepted for backwards compatibility if `language` is not provided.

API responses from `GET /v2/knowledge/articles` and `GET /v2/knowledge/articles/{id}` will continue to return `locale`, but it is no longer documented. In these responses, the `language` field contains the ISO 639-1 two-character language code, not the full BCP 47 tag.

This is part of a gradual migration. Eventually, `locale` will be removed from both persisted records and API responses, and `language` will consistently use BCP 47 tags across all endpoints.

## New callback event in Embed2

We've added a new event to the [`subscribeEvent`](/reference/embed2-reference#subscribeevent) action in Embed2. With this event, you can receive a callback when an end user submits a CSAT. The event returns a numeric CSAT score:

| Event key            | Trigger                                           |
| :------------------- | :------------------------------------------------ |
| `ada:csat_submitted` | Triggered when the full screen CSAT is submitted. |

If you're using the Embed2 script, these events are immediately available. For the [NPM package](https://www.npmjs.com/package/@ada-support/embed2), update it to the latest version (1.8.16) to start using them.

## Validation added to reply_to field in Email Conversation API

Validation for the `reply_to` field in the Email Conversation API will be introduced in the coming weeks. Once implemented, requests with an invalid email address will fail with a validation error.

## v2 API release

Ada is releasing a new version (v2) of our platform APIs. For detailed instructions on how to migrate your integrations, please see our [Migration Guide](https://developers.ada.cx/reference/introduction/migrate-to-v-2).

In addition to an updated developer documentation site, we're adding the following capabilities to our platform in this release:

**API Endpoints Consolidation**

Several legacy endpoints have been merged and restructured by resource and action. This makes integrations simpler and reduces redundancy. For example:

* v1: `https://example.ada.support/api/end-users/v1/`
* v2: `https://example.ada.support/api/v2/end-users/`

**Streamlined API Tokens**

A single API token now works across all endpoints. Previously, separate tokens were required per API. This change simplifies token management and authentication.

**Uniform Response Structures**

Responses (including error messages) are now standardized. This reduces the complexity of handling different response formats and improves overall consistency.

**Standardized Pagination**

Pagination parameters and response metadata are now consistent, enhancing the developer experience when handling large data sets.

**Improved Rate & Data Limits**

More transparent rate and data limit policies have been introduced. This ensures better reliability, prevents unexpected throttling, and makes it easier to plan request volumes.

**Data Export API Updates**

The Data Export API endpoints have been updated to follow the new v2 naming convention:

* `/api/data_api/v1.4/conversations` → `/api/v2/export/conversations`
* `/api/data_api/v1.4/messages` → `/api/v2/export/messages`

**Backward-Incompatible Changes**

Some v1 functionality has been deprecated or altered. Review your current integrations and ensure you’re using the appropriate v2 endpoints and parameters.

## Embed2 security improvements

We've released some security improvements to Embed2.

* If you're using the Embed2 [NPM package](https://www.npmjs.com/package/@ada-support/embed2) , upgrade it to version **1.7.27 or newer**.
* The Embed2 script is versionless and gets automatic updates, so if you're using it, you can already access the upgrades.

## setSensitiveMetaFields Embed2 Action now supported in Generative

Previously the [setSensitiveMetaFields action in Embed2](https://developers.ada.cx/reference/embed2-reference#setsensitivemetafields) action and [sensitiveMetaFields](https://developers.ada.cx/reference/embed2-reference#sensitivemetafields) setting were only supported in scripted bots, now it is supported in Generative AI Agents.

## Embed2 security improvements

We've released some security improvements to Embed2.

* If you're using the Embed2 [NPM package](https://www.npmjs.com/package/@ada-support/embed2) , upgrade it to version **1.7.18 or newer**.
* The Embed2 script is versionless and gets automatic updates, so if you're using it, you can already access the upgrades.

## New callback events in Embed2

We've added three new events to the [`subscribeEvent`](/reference/embed2-reference#subscribeevent) action in Embed2. With these events, you can provide your clients with a better experience after a bot or AI Agent has handed the conversation off to a human agent:

| Event key                  | Trigger                       |
| :------------------------- | :---------------------------- |
| `ada:agent:joined`         | Agent joined the conversation |
| `ada:agent:left`           | Agent left the conversation   |
| `ada:conversation:message` | Customer received a message   |

If you're using the Embed2 script, these events are immediately available. If you're using the [NPM package](https://www.npmjs.com/package/@ada-support/embed2), update it to the latest version (1.7.17) to start using them.

## New conversation topic fields

We've added multiple fields to the Data Export API's [Conversation object](/reference/data-export-conversation-object):

* `generated_topic_v2_desc`
* `generated_topic_v2_id`
* `generated_topic_v2_parent_id`
* `generated_topic_v2_title`

These are to support the enhancements we made to conversation topics, which we released in May 2024. Those enhancements improved the classifications in your AI Agent's automatic topic classifications, and now you can access that new data via API. The older topics fields, `generated_topic_id` and `generated_topic_label`, are still available so you can access information about older conversation topics.

## New tags in End User API webhook payloads

When you're [creating](/reference/manually-created-webhook-page) or [updating](/reference/webhook-end-user-updated) users with webhooks in the End User API, you'll now see `tags` that you can use to filter webhook events on the Ada dashboard. You can currently use this tag to filter webhook events by End User ID.

## Create global keys to use with all of your Ada APIs

Until now, if you've used multiple Ada APIs, you've had to create and manage different keys for each one. Now, you have the option to create one or more global keys that work across all of Ada's current and future platform APIs.

All of your existing API-specific keys will continue to work, and will still be specific to the APIs they were originally generated for. They'll be marked as legacy keys in your dashboard, so you can tell them apart from your global keys.

For more information, see [Authorize API integrations](https://developers.ada.cx/reference/authentication).

## New fields in the Data Export API

We have added multiple fields to the Data Export API. Click through to each object type to learn more:

* **[Conversation object](/reference/data-export-conversation-object)**
  * `agent_handle_time`
  * `bot_handle_time`
  * `record_last_updated`
* **[Message object](/reference/data-export-message-object)**
  * `record_last_updated`

## Add IDs and metadata to sources in the Knowledge API

To make it easier to manage your knowledge base's sources, you now have the option to add information into `external_id` and `metadata` fields when you [create](/reference/create-knowledge-source) or [update](/reference/update-knowledge-source) a knowledge source.

## Filter articles in the Knowledge API

You can now filter knowledge articles to make bulk GET and DELETE requests, based on any combination of these attributes:

* Article IDs
* Whether articles are enabled
* Knowledge sources articles belong to
* Languages articles are in
* Tags assigned to articles

For more information, see [Get multiple articles](/reference/get-knowledge-articles) and [Delete multiple articles](/reference/delete-knowledge-articles).

## Article tags in the Knowledge API

We have added the ability to create [article tags](/reference/tags-knowledge-api) (e.g,. "merchants," "customers," "promotions," etc.) in the Knowledge API. Then, on your Ada dashboard, you'll be able to use those tags to filter the articles in your knowledge hub, and set customized availability rules for them.

## End user ID in the Data Export API

We have added an `end_user_id` attribute to the [`Conversation` object](/reference/data-export-conversation-object) in version 1.4 of the Data Export API.

## End User API release

We have released the [End Users API](/reference/overview-end-users-api), which allows you to to update and manage your users' data in real time. It also comes with webhook events you can subscribe to so you can keep track of changes to user profiles in Ada.

## Data Export API v1.4 release and other improvements

* We have released Version 1.4 of the [Data Export API](https://developers.ada.cx/reference/overview-data-export), which includes new topic fields in conversation objects.
* For Version 1.3, we have implemented the following improvements:
  * We no longer truncate variables that are more than 1000 characters long.
  * We fixed a bug that only affected Version 1.3, where all variable and metavariable values were lowercase. They are now case-sensitive.
* For all versions of the API, API threshold errors now return 429 instead of 500 status codes.

_Showing the 20 most recent of 28 entries. Append `/llms.txt` to the changelog URL for the complete index._