> 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/whatsapp.md). # WhatsApp The platform exposes separate paths for WhatsApp-style text and voice-note turns. The integration receiving the inbound message chooses the path that matches the media it received; the public Platform contract does not currently expose a per-number `response_modality` setting. | Path | Input | Output | Continuity | | -------------- | ------------------------------------------- | ---------------------------------------- | --------------------------- | | **Text turn** | Customer phone, business phone, and text | Text reply or no-content response | Durable text conversation | | **Voice turn** | Customer phone and supported recorded audio | Synthesized audio or no-content response | Separate audio-turn session | Text and voice-note histories are not merged. A workflow that supports both must decide which path to invoke and must not assume that context from one mode is automatically present in the other. ## Text Turns The text-turn API validates the workspace and service, then runs a single WhatsApp-style message through the durable text-session pipeline. The business phone participates in the provider thread key so repeat messages from one customer to one business number resolve to the appropriate text conversation. The response contains the agent's text or returns no content when the engine elects silence. The endpoint is synchronous and enforces one in-flight turn for a speaker; a conflicting concurrent turn returns a conflict response. Managed inbound processing can coalesce message signals already queued behind a running durable-channel turn, but API clients should serialize their own requests. Text turns use the bound service's Context Graph and eligible tools. Tool availability, integration approval, and downstream write policy remain configuration dependent. ## Voice-Note Turns The voice-turn API accepts supported recorded audio, transcribes it, runs the reasoning pipeline, synthesizes the agent reply, and returns audio. The current response is OGG Opus when speech is produced; a no-content response means the engine elected silence. Voice-note sessions are keyed by workspace, service, and customer phone. They serialize turns for the same speaker but retain state separately from WhatsApp text conversations. Voice notes do not provide the continuous media stream, barge-in, live takeover, or acoustic timeline of a phone call. ## Text Conversation Continuity Text history remains attached to a durable conversation and is retrievable when its conversation ID is known. A non-terminal provider thread can resume after the active actor becomes idle. A new text thread starts after terminal Context Graph completion or an explicit close of the known conversation. The Conversations API does not currently support outbound WhatsApp creation or `force_new` for WhatsApp. There is no patient-facing reset keyword. See [Phone-Keyed Threads](/channels/text-sessions.md#phone-keyed-threads) for the shared lifecycle model. ## Background Work and Delivery The WhatsApp text channel uses the non-live background-work policy: it suppresses an intermediate filler response and attempts to re-drive the final reply after supported work completes. Tool completion, channel acceptance, and recipient delivery remain separate. Check channel status and retry evidence instead of treating a completed agent turn as proof of delivery. The direct voice-turn API is request scoped. Its caller receives the audio response, a no-content response, or an error on that request; it is not a persistent voice-note socket. ## Operational Boundaries * Normalize customer and business phone numbers to E.164. * Serialize turns for the same customer and mode. * Route text and audio explicitly; do not depend on an undocumented number-level modality switch. * Treat text and voice-note state as separate. * Use a live [phone call](/channels/voice.md) when the workflow needs real-time audio controls. {% content-ref url="/pages/F9G0lrxZA31mW1pawkgs" %} [Text Sessions](/channels/text-sessions.md) {% endcontent-ref %} --- # 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/whatsapp.md?ask=&goal= ``` `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.