Copy page

Core Concepts

Conversations

A conversation is a single thread of messages and voice sessions exchanged with one contact through one channel. Whether you're texting a lead via SMS, replying on WhatsApp, or following up with a voice call, every interaction lives under one conversation_id so analytics, context, and dynamic variables stay consistent across modalities.

Conversation vs voice session

These are two distinct resources that often refer to each other.

	Conversation	Voice Session
Resource	/v1/conversations/*	/v1/voice-sessions/*
Lifetime	Long-lived thread; spans multiple calls or messages	Single call (inbound, outbound, or web)
Contains	Messages + voice session pointers + dynamic_variables	Transcript, recording, post-call analysis
Channels	sms, whatsapp, voice	phone, web, whatsapp_voice
Use it for	Inbox-style review, sending replies, multi-turn context	Real-time call control, live monitoring, post-call analytics

A WhatsApp voice session, for example, has both: a voice_session for the call mechanics and a conversation representing the thread it landed in.

Lifecycle

1. Created when the first message lands (inbound or outbound) or a voice session opens
2. Active while messages or calls continue
3. Closed / dormant after a configurable idle window (24h on WhatsApp by Meta policy; longer on SMS / voice)
4. Reopened if a new message arrives — the platform reuses the same conversation_id rather than creating a new thread, so context and dynamic_variables carry over

Dynamic variables on conversations

Every conversation carries a dynamic_variables dict that the agent's prompt template renders against on every turn. This is how you persist context across multiple voice calls in the same thread without rebuilding it on each call. See Dynamic variables and Inbound variable injection for the full data flow.

Update them at any time:

Code
client.conversations.update_dynamic_variables(
    conversation_id="conv_01HX...",
    dynamic_variables={"appointment_confirmed": "true", "next_step": "send_invoice"},
    replace=False,  # merge into existing dict; True replaces wholesale
)

API surface

Eight endpoints under /v1/conversations/*:

Method	Path	Purpose
GET	/v1/conversations	List threads
GET	/v1/conversations/{id}	Get a single thread
GET	/v1/conversations/{id}/messages	List messages in a thread
POST	/v1/conversations/{id}/messages	Send a reply
POST	/v1/conversations/{id}/read	Mark all messages read
GET	/v1/conversations/{id}/timeline	Unified messages + voice sessions
PATCH	/v1/conversations/{id}/dynamic_variables	Update variables
GET	/v1/conversations/analytics/dashboard	Per-org chat KPIs

Sending a message

The send body uses body (the message text), not text:

Code
client.conversations.send_message(
    conversation_id="conv_01HX...",
    body="Hi Alice — your appointment is confirmed for Thursday at 10am.",
    media_urls=["https://your-cdn.example.com/confirmation.png"],  # optional
)

Code
await client.conversations.sendMessage("conv_01HX...", {
  body: "Hi Alice — your appointment is confirmed for Thursday at 10am.",
});

For WhatsApp template messages (the only allowed shape outside the 24h customer-service window), configure the template on the agent and the platform sends it automatically when the conversation reopens. See WhatsApp integration.

Timeline

The timeline endpoint interleaves messages and voice sessions chronologically — useful when a contact has both chat and call history in the same thread:

Code
events = client.conversations.timeline("conv_01HX...", limit=20)
for ev in events["results"]:
    print(ev["timestamp"], ev["type"], ev.get("preview"))

type is one of message, voice_session_started, voice_session_ended.

Related

• Messaging overview
• WhatsApp integration
• SMS messaging
• Inbound variable injection