> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/channels/text-sessions.md).

# Text Sessions

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.

{% hint style="info" %}
Endpoint details and examples are in the [Conversations API guide](https://docs.amigo.ai/developer-guide/platform-api/conversations).
{% endhint %}

### 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](/platform-overview/deployment-model.md#version-sets). 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.

{% content-ref url="/pages/06YznjcZmK794tiVzM7q" %}
[SMS](/channels/sms.md)
{% endcontent-ref %}

### 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.

{% content-ref url="/pages/c1iRKBkz9pUpCgeAnQTO" %}
[iMessage](/channels/imessage.md)
{% endcontent-ref %}

### 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.

{% content-ref url="/pages/SS3ZnjwCmfLJCyDs8hcQ" %}
[WhatsApp](/channels/whatsapp.md)
{% endcontent-ref %}

### Email

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

{% content-ref url="/pages/uirHtW6W7wkJL0eKBdYK" %}
[Email](/channels/email.md)
{% endcontent-ref %}

## 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](/testing/testing/playground.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/channels/text-sessions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.