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. 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.	Your application, via the Assistants API.
websocket_call	One conversation per realtime WebSocket connection.	The platform, at socket start.
web_call	Assistant test runs executed from the portal test simulator.	A test run or the portal.

Conversation metadata

Each conversation carries identifying metadata you can read on every list and get 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: {{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 can span both by querying on telnyx_end_user_target without a channel filter.

Querying conversations by channel or participant

The List Conversations endpoint 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

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.