Text Sessions

Durable text conversations over the web API, SMS, iMessage, WhatsApp, and email, with channel-specific delivery behavior.

Text sessions run the agent's core reasoning and Context Graph behavior without the live audio pipeline. The bound service determines the agent configuration and eligible tools; each channel adds its own identity, delivery, timing, and operator controls.

The public web integration uses the Conversations REST API. A turn can return one JSON response or stream typed Server-Sent Events (SSE). The platform does not currently expose a public text-session WebSocket.

Durable Conversation Model

The platform persists text turns against a conversation ID. Conversation detail exposes the durable history, current status, and channel attribution needed to resume or inspect a thread. Channel runtimes can keep short-lived actor state for active work, but an idle actor does not erase the durable conversation.

The public conversation resource separates two concepts:

• Status records the stored processing state, such as active, completed, closed, paused, or failed where applicable.
• Lifecycle is a read-time view of recency: active, dormant, or closed. A dormant conversation is idle, not deleted.

Do not treat lifecycle as a guarantee that an actor is resident in memory. Resume behavior depends on the channel, conversation status, provider thread key, and current service configuration.

Phone-Keyed Threads

SMS, iMessage, and text-mode WhatsApp resolve inbound messages through provider thread keys. While a non-terminal conversation remains available for that key, later messages resume it and retain its durable turn history.

A new thread starts after terminal Context Graph completion or an explicit lifecycle change. For SMS and iMessage, outbound creation also accepts force_new: true; the platform closes the active conversation for the same recipient and use case before dispatching a new opener. Outbound WhatsApp creation is not supported by this conversation-start path.

There is no patient-facing reset keyword. If an application needs a deterministic reset, retain the conversation ID and close it through the lifecycle API before the next inbound message.

Endpoint details and examples are in the Conversations API guide.

Configuration Changes

Published service configuration and version-set bindings determine what a conversation loads. An already active channel actor can retain configuration it loaded earlier, so a newly published version is not guaranteed to affect the very next inbound message.

For a controlled rollout, pin the intended versions in the service's release version set. When a structural change is incompatible with an in-progress thread, close the conversation and start a new one rather than relying on a mid-thread reload.

Supported Text Paths

Path	Continuity	Response behavior
Web API	A caller creates a web conversation and sends turns by conversation ID	Synchronous JSON or request-scoped SSE
SMS	Provider thread resolves to a durable conversation	Asynchronous provider delivery
iMessage	Provider thread resolves to a durable conversation	Asynchronous provider delivery with supported media
WhatsApp text	Customer and business-number thread resolves to a durable conversation	Synchronous text-turn response to the channel integration
Email	Message headers and stored references preserve email threading	Asynchronous email reply delivery

WhatsApp voice notes use a separate audio-turn path and separate session state. They do not merge with the number's durable WhatsApp text history.

Web Conversations: REST and SSE

A web client first creates a conversation for a service, then sends one turn at a time to that conversation.

Synchronous JSON

The standard turn request returns the user's input, agent output, conversation snapshot, and optional tool-call details in one response. Serialize turns per conversation: do not submit another user turn while the current one is still in flight.

Server-Sent Events

For incremental output, use the dedicated streaming turn endpoint or request Accept: text/event-stream on the standard turn endpoint. The stream can emit:

• token
• tool_call_started
• tool_call_completed
• thinking
• message
• done
• error

These are request-scoped events, not a persistent bidirectional session. A client should handle an error event and an interrupted HTTP connection explicitly.

Background Tool Completion

A synchronous response can return background_pending: true when a tool outlives the blocking window. In that case, the returned output is an acknowledgement, not the final answer.

Clients have two supported controls:

1. Set wait_for_final: true on the message turn to wait for the final answer for a bounded period.
2. If the response still reports pending work, send a no-message request with poll=true until the completion is returned. Do not combine polling with SSE or a user message, and avoid polling more often than the documented interval.

Sending the next user turn can also drain completed background work, but applications that need the result before accepting more input should poll explicitly. An open WebSocket is not part of this completion protocol.

Asynchronous Channel Delivery

SMS, iMessage, WhatsApp, and email use non-live channel policies. When supported background work is handed off, the channel runtime suppresses an intermediate filler response and attempts to re-drive the conversation when the result completes.

That behavior does not make external delivery infallible. Provider rejection, opt-out policy, invalid addressing, or exhausted retries can still prevent the final message from reaching the recipient. Use the channel's delivery status and recovery controls rather than treating agent completion as proof of delivery.

Message Coalescing

SMS, iMessage, and WhatsApp can coalesce messages that accumulate while a turn is already processing. Up to ten queued message signals can become the next agent turn. This prevents several rapid fragments from producing several overlapping replies.

Web API and email turns are not coalesced. Non-message signals remain separate.

Channel Notes

SMS

SMS supports inbound durable threads and outbound openers through provisioned use cases. Sender selection, opt-out enforcement, media support, and delivery status belong to the SMS channel contract.

SMS

iMessage

iMessage uses a managed channel setup and durable phone-keyed conversations. The public lifecycle API supports outbound openers and explicit switching between SMS and iMessage.

iMessage

WhatsApp

WhatsApp exposes separate text-turn and voice-turn paths. The text path returns text and preserves a durable thread; the voice-note path transcribes audio and returns synthesized audio with separate continuity.

WhatsApp

Email

Email uses message headers and stored references to preserve reply threading. Its delivery, suppression, attachment, and recovery behavior is documented separately.

Email

Differences from Voice

Text behavior	Operational consequence
No real-time audio pipeline	No barge-in, filler speech, or acoustic emotion evidence
Request- or message-driven turns	Delivery and response timing depend on the channel
Durable asynchronous threads	A later message can resume a non-terminal conversation
Authored-turn takeover on eligible non-voice runs	Operators stage a reply instead of joining an audio conference

Text channels can use language-level safety and sentiment signals where configured, but they do not have the vocal evidence available to a live phone call.

Playground Testing

Open Prove > Playground in the Developer Console. The playground has two modes:

• Voice for eligible voice services
• Text for eligible voice or text services

Text mode creates a durable web conversation and streams each turn over SSE. It can show optional Context Graph and Timeline panels; it is not a separate REST, realtime, or WebSocket mode. See Playground and Interactive Testing.