> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How conversations are keyed across channels

> How Telnyx AI Assistants conversations are keyed across phone calls, SMS, WhatsApp, web chat, and realtime WebSocket sessions — the metadata that identifies a conversation and how to query conversations by channel and participant.

Every interaction between an AI Assistant and an end user is stored as a conversation in [AI Conversations](/api-reference/conversations/list-conversations). Conversations are keyed by channel and by the two endpoints of the conversation — the assistant's target (a phone number, SIP URI, or other identifier) and the end user's target — and the same assistant can have several independent conversations with the same end user, one per channel.

## Keying model per channel

| Channel          | Conversation granularity                                                                                                                 | Created by                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `phone_call`     | One conversation per phone call, inbound or outbound.                                                                                    | The platform, at call setup.                                                |
| `sms_chat`       | One long-lived conversation per (assistant number, end-user number) pair. Texts between the same pair continue in the same conversation. | The platform, at the first text.                                            |
| `whatsapp_chat`  | WhatsApp texts, marked with this channel by the messaging system.                                                                        | The platform.                                                               |
| `web_chat`       | One conversation per `conversation_id` you pass to the [chat endpoint](/api-reference/assistants/create-assistant-chat-completion).      | Your application, via the Assistants API.                                   |
| `websocket_call` | One conversation per realtime [WebSocket connection](/docs/inference/ai-assistants/realtime-conversations).                              | The platform, at socket start.                                              |
| `web_call`       | Assistant test runs executed from the portal test simulator.                                                                             | A [test run](/docs/inference/ai-assistants/scheduled-events) or the portal. |

## Conversation metadata

Each conversation carries identifying metadata you can read on every [list](/api-reference/conversations/list-conversations) and [get](/api-reference/conversations/get-conversation) response:

| Field                                               | Present on   | Description                                                                               |
| --------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------- |
| `assistant_id`                                      | All channels | The assistant the conversation belongs to.                                                |
| `telnyx_conversation_channel`                       | All channels | The channel the conversation runs on — see the table above.                               |
| `telnyx_agent_target`                               | All channels | The assistant's target: the phone number the assistant answers on, or another identifier. |
| `telnyx_end_user_target`                            | All channels | The end user's target: the caller's phone number, or another identifier.                  |
| `call_control_id`, `call_session_id`, `call_leg_id` | `phone_call` | The Call Control identifiers of the call the conversation belongs to.                     |

The same fields are available to the assistant's instructions and tools as [dynamic variables](/docs/inference/ai-assistants/dynamic-variables): `{{telnyx_conversation_channel}}`, `{{telnyx_agent_target}}`, and `{{telnyx_end_user_target}}`.

## One pair, one conversation per channel

A single number pair — one assistant number and one end-user number — can have several concurrent or sequential conversations, one per channel. A phone call to the assistant's number creates a `phone_call` conversation for that call, while texts with the same number pair continue in their own long-lived `sms_chat` conversation. The two records are independent: closing the call does not close the text conversation, and the assistant's [memory](/docs/inference/ai-assistants/memory) can span both by querying on `telnyx_end_user_target` without a channel filter.

## Querying conversations by channel or participant

The [List Conversations endpoint](/api-reference/conversations/list-conversations) filters on any metadata field using PostgREST-style parameters.

All SMS conversations with one end user:

```
GET /v2/ai/conversations?metadata->telnyx_conversation_channel=eq.sms_chat&metadata->telnyx_end_user_target=eq.+13125550123
```

Every conversation — calls and texts — between one number pair:

```
GET /v2/ai/conversations?metadata->telnyx_agent_target=eq.+13125550100&metadata->telnyx_end_user_target=eq.+13125550123
```

Phone-call conversations created in a window:

```
GET /v2/ai/conversations?metadata->telnyx_conversation_channel=eq.phone_call&created_at=gte.2026-09-01&created_at=lt.2026-10-01
```

<Note>
  Message rows carry channel metadata too: a turn recorded with `telnyx_conversation_channel: sms_chat` inside a conversation whose own channel is `phone_call` did not come from the call. When inspecting a transcript, read the channel on both the conversation and each message.
</Note>