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

# Conversation identifiers and persistence

## Overview

Ada assigns identifiers to help track users and Conversations across [Channels](/docs/channels). These identifiers determine when a conversation begins and ends, how messages are grouped, and whether a returning user is recognized or treated as new. Persistence settings, user behavior, and channel differences all influence how these identifiers change over time.

This topic explains [how conversation and user identifiers relate to each other](#how-identifiers-relate), [how they are assigned](#conversation-and-user-identifiers), and [how persistence governs session continuity](#persistence-and-session-continuity) across [Chat](/docs/channels/chat), [Email](/docs/channels/email), [Social](/docs/channels/social), and [Voice](/docs/channels/voice) interactions. It also includes [examples](#examples) that illustrate how identifiers behave in different scenarios.

To learn how variables are stored and reused during conversations, see [this section](/docs/automation/variables).

## Conversation and user identifiers

Ada uses several identifiers to represent different levels of user and conversation context.

### `conversation_id`

Represents a single conversation thread. A new `conversation_id` is created when:

* a new Web Chat session begins
* a previous conversation times out
* the user manually ends chat (depending on persistence)
* an email reply arrives outside the continuation window
* a social platform creates a new messaging thread
* a call begins in a voice channel

`conversation_id` is included in [data exports](/docs/optimization/conversations/data-export).

### `chatter_id`

Represents the browser or device session for Web Chat. A single `chatter_id` may map to several different `conversation_id` values. It appears in the **Convos** view under **Meta variables**.

![chatter\_id](/_fern-img/402d98c1bf0f2a6d1a74d1eef29a38ed41b1f696d238934bfa80a12a6e40b360.webp)

### `end_user_id`

A persistent identifier that represents a user across multiple conversations and channels. It remains stable if the user can be recognized based on persistence rules or channel metadata. This identifier also appears in the **Convos** view under **Meta variables**.

![end\_user\_id](/_fern-img/3d3c07568883cc3a8b213dc9d85297d2a301d42afde1bf02dc344ab9585fba76.webp)

### Sunshine Conversations identifiers

For social channels integrated through Sunshine Conversations, your AI Agent may receive external identifiers from the messaging platform. These can include:

* `sunshine_user_id`: The user identifier provided by the external platform.
* `sunshine_conversation_id`: The thread or conversation identifier provided by the external platform.

These values appear when Sunshine Conversations is enabled. They reflect identifiers used by the external platform and can help correlate your Agent's conversations with activity occurring on that platform.

## How identifiers relate

Each identifier represents a different layer of identity:

* `end_user_id`: The end user record created for a given interaction
* `chatter_id`: The session-level identity used during that interaction
* `conversation_id`: The specific conversation thread

**Each `end_user_id` corresponds to exactly one `chatter_id`, and Ada treats them as a 1:1 representation of the same underlying user.**

However, when your system tracks end users by its own stable identifier, the [End Users API](/reference/end-users/overview) can associate that identifier with the Ada end user through the `external_id` field. This is supported for custom channel (Conversations API) integrations: set `external_id` at creation, and subsequent inbound interactions can look up the same end user by calling `GET /v2/end-users/?external_id=<value>` to retrieve the existing `end_user_id` and continue the conversation with a hydrated profile.

### What that means

* **Inside Ada**: `end_user_id` and `chatter_id` are separate identifiers but always refer to the same individual.
* **Inside your system**: For custom channel integrations, use the `external_id` field to recognize returning end users by your own identifier (for example a CRM contact ID) and reuse the same Ada end user across conversations. `external_id` is unique per AI Agent — one value maps to exactly one end user.
* **They are not interchangeable** and appear in different contexts (e.g., [embed](/chat/introduction/overview) exposes `chatter_id`, while the [End Users API](/reference/end-users/overview) references `end_user_id`).

This ensures Ada can track each session independently while giving you flexibility to recognize returning end users at the application level. See [Examples](#examples) for how a custom channel integration can use `external_id` to recognize returning end users.

## Persistence and session continuity

Web Chat includes [configurable persistence settings](/docs/channels/chat/chat-configuration/data-controls#persistence-settings) that determine how returning visitors are recognized. Persistence is evaluated only when the chat widget loads or refreshes.

### Effects of persistence

In Messaging, **Forget After Reload** preserves an active handoff across a page refresh; `privateMode` preserves no browser session state. See [Messaging data controls](/docs/channels/messaging/messaging-configuration/data-controls) for this exception.

| Persistence setting                                                       | Action                            | Result                                                       | Notes                                                     |
| ------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| **Forget After Tab Close**                                                | Close and reopen tab              | New `conversation_id`, new `chatter_id`, new `end_user_id`   | Each tab is treated as its own session                    |
| **Forget After Reload**                                                   | Refresh the page                  | New `conversation_id`, new `chatter_id`, new `end_user_id`   |                                                           |
| **Forget After `X` time**                                                 | Refresh after `X` time            | New `conversation_id`, new `chatter_id`, new `end_user_id`   | Users are not forced out mid-session                      |
| **Any Forget setting**                                                    | User ends chat                    | New `conversation_id`, same `chatter_id`, same `end_user_id` | Variable reuse depends on session continuity              |
| **Never Forget**                                                          | 24 hours pass with no user action | New `conversation_id`, same `chatter_id`, same `end_user_id` |                                                           |
| **Any**                                                                   | Cookies cleared                   | New `conversation_id`, new `chatter_id`, new `end_user_id`   | Clearing storage resets identity                          |
| **Any**                                                                   | Email or ticket handoff           | New `conversation_id`, same `chatter_id`, same `end_user_id` |                                                           |
| **Embed:[`reset()`](/chat/web/sdk-api-reference#reset)**                  | `reset()` triggered               | New `chatter_id`, new `end_user_id`                          | Assigned even during an active conversation               |
| **Embed: [`deleteHistory()`](/chat/web/sdk-api-reference#deletehistory)** | `deleteHistory()` then refresh    | New `chatter_id`, new `end_user_id`                          |                                                           |
| **Embed: [`privateMode`](/chat/web/sdk-api-reference#privatemode)**       | Refresh in `privateMode`          | New `conversation_id`, new `chatter_id`, new `end_user_id`   | Keeps no browser session state, including during handoffs |

## Conversation timeouts

Conversations end automatically after long periods of inactivity:

* Web Chat and most messaging channels: about 24 hours
* Email: about 72 hours

After timeout, the next message creates a new `conversation_id`.

Ada also generates a new `chatter_id`/`end_user_id` pair for the session. If you want to link session-level identities across devices or time, you can do so using the [End Users API](/reference/end-users/overview). See [How identifiers relate](#how-identifiers-relate) for a full explanation of how these values work together.

## Cross-channel behavior

For Messaging, [identity tokens](/messaging/identity/overview#one-conversation-across-every-device) restore the same end user and conversation across devices. Follow [Personalization and identity](/docs/channels/messaging/personalization-and-identity) for backend lookup and session setup.

Identifiers and session continuity behave differently depending on the [Channel](/docs/channels) where the conversation occurs. Each channel has its own rules for how users are recognized, how conversations are grouped, and when new sessions begin. The sections below outline how identity and conversation behavior work across channels.

#### Web Chat

* Persistence determines session continuity
* Refreshing, closing tabs, and clearing cookies affect `chatter_id`
* `conversation_id` resets based on session continuity and timeouts

#### Email

* Identity is based on email address
* Time windows determine conversation grouping

#### Social messaging

* Identity and session continuity rely on Sunshine platform identifiers
* Multiple Ada conversations may originate from one external thread

#### Voice

* Identity is determined by caller phone number
* Each call typically creates a new conversation

## Shared devices

When multiple users share a device, identity should be reset to avoid cross-user data exposure. In Web Chat implementations using the Chat SDK (embed), call [reset()](/chat/web/sdk-api-reference#reset) on logout to generate a new `chatter_id` and ensure [variables](/docs/automation/variables) and prior conversation context are not reused.

## Examples

Use these examples to see how conversation identifiers and persistence behave in real situations. Each scenario highlights how user actions, browser behavior, or channel rules influence whether Ada creates a new conversation or reuses an existing identity.

#### Returning user in Web Chat with 'Never Forget'

1. End user starts chatting with the AI Agent.
2. `chatter_id` and `end_user_id` are assigned.
3. End user returns later in the same browser.
4. A new `conversation_id` is created, but the same `end_user_id` continues.
5. Persisted variables associated with identity may still be available.

#### Page refresh with 'Forget After Reload'

1. End user begins a Web Chat session.
2. They refresh the page.
3. A new `chatter_id` and new `conversation_id` are created.
4. The user appears as new.

#### Email reply outside continuation window

1. End user emails your support address.
2. Ada responds, creating a conversation.
3. User replies after several days.
4. A new `conversation_id` is created, but the same `end_user_id` is used.

#### Shared device logout

1. Person A interacts with the AI Agent through Web Chat.
2. They log out of your application.
3. [`reset()`](/chat/web/sdk-api-reference#reset) is called.
4. Person B logs in.
5. A new `chatter_id` ensures their sessions remain distinct.

#### Recognizing returning end users with external\_id (custom channels)

This pattern applies only to custom channels through the Conversations API. For Messaging, use backend lookup with [identity tokens](/messaging/identity/getting-started) instead of the custom-channel conversation creation flow.

1. An end user contacts the AI Agent for the first time through a custom channel. The integration has a stable identifier for the user in its own system (for example `CRM_12345`).
2. The integration calls `GET /v2/end-users/?external_id=CRM_12345` — a `404` response indicates no Ada end user is mapped to that value yet.
3. The integration calls `POST /v2/end-users/` with `external_id: "CRM_12345"` and any known profile fields (language, metadata). Ada creates the end user with `201` and stores the mapping.
4. The integration starts a conversation using the returned `end_user_id`.
5. Later, the same end user contacts the AI Agent again. The integration calls `GET /v2/end-users/?external_id=CRM_12345` — this time a `200` response returns the existing `end_user_id` and profile data.
6. The integration starts a new conversation on the same `end_user_id`. Ada links both conversations to the same end user record.

In this scenario, the integration uses its own identifier as the lookup key, and Ada maintains the link between that identifier and the end user across conversations. For the full pattern, see [Identify end users with a stable external ID](/reference/end-users/developer-guide#identify-end-users-with-a-stable-external-id).

## Related features

* [Persistence settings](/docs/channels/chat/chat-configuration/data-controls#persistence-settings): Configure how returning visitors are recognized and when session identifiers reset.
* [Variables](/docs/automation/variables): Store and reuse data during conversations, with persistence tied to session continuity.
* [Data export](/docs/optimization/conversations/data-export): Export conversation data, including `conversation_id` and other identifiers.
* [Data retention](/docs/other/data-retention): Understand how long conversation data is stored before deletion.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).