> 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/conversations.md). # Overview Amigo is a reasoning engine that works across channels. Voice calls, SMS conversations, WhatsApp messages, email, and web-based data collection share the same core pipeline. The agent reuses context graphs, eligible tools, safety policy, and world-model context while each channel applies its own delivery and control capabilities. Healthcare workflows rarely fit neatly into one channel. A patient might answer a phone call, receive a link to a photo upload form, and get a reminder message the next day. Shared agent and world-model context can coordinate those touchpoints even when transport-specific conversations retain separate session state. ```mermaid flowchart TD phone["Phone\n(real-time voice)"] --> engine["Reasoning Engine\n(context graphs + tools + safety)"] sms["SMS"] --> engine whatsapp["WhatsApp\n(text + voice notes)"] --> engine webapi["Web app / API\n(REST + SSE)"] --> engine email["Email\n(transactional, marketing)"] --> engine surfaces["Surfaces\n(web forms)"] --> engine engine --> wm["World Model"] ``` ## How It Works The platform's [reasoning engine](/agent/reasoning-engine.md) operates on a signal-and-effect model. Signals arrive from any channel - a voice utterance, a text message, a form submission - and the engine processes them through the agent's context graph, runs tools, applies safety checks, and emits effects. Those effects route back to whichever channel is appropriate: spoken audio, a text reply, a surface link. The engine is channel-agnostic - modality adapters handle the translation on both sides. Multi-channel orchestration works without duplicating agent logic. ## Background Tool Delivery on Non-Live Channels Voice, web API, and asynchronous messaging expose different completion contracts. A web turn can return synchronous JSON, stream request-scoped SSE, or report `background_pending` for bounded waiting and explicit polling. Email, SMS, iMessage, and WhatsApp use non-live policies that suppress filler and attempt to re-drive a reply when supported background work completes. Provider delivery is still separate: opt-out, rejection, retries, and channel outages can prevent the final message from reaching the recipient. ## Channel Types ### Phone Real-time phone conversations with speech recognition, natural speech generation, and emotion detection. The agent calibrates emotional analysis to each caller's own vocal baseline, interprets emotional signals in the context of the conversation state, and adapts its tone and pacing accordingly. The agent handles inbound and outbound calls, manages turn-taking, and escalates to human operators when needed. Phone is the highest-bandwidth channel for complex discussions like care coordination or clinical verification. See [Phone](/channels/voice.md) for details on the audio pipeline, emotion detection, and operator escalation. ### Text Sessions Text-based conversations over the web API, SMS, iMessage, email, and text-mode WhatsApp use durable conversation records. They support the same core Context Graph model and eligible tools as phone, with channel-specific delivery behavior. WhatsApp also has a separate voice-note path whose state is not merged into the durable text thread. See [Text Sessions](/channels/text-sessions.md) for REST/SSE behavior, durable-channel continuity, and differences from phone. SMS has its own provisioning and compliance flow covered in [SMS](/channels/sms.md). ### WhatsApp Business messaging over WhatsApp follows the durable text session path used by other asynchronous text channels. Conversations are keyed on the customer and agent phone pair, so a returning customer resumes the same text thread rather than starting a new one. WhatsApp voice-note mode retains separate state. {% content-ref url="/pages/SS3ZnjwCmfLJCyDs8hcQ" %} [WhatsApp](/channels/whatsapp.md) {% endcontent-ref %} ### iMessage Patient messaging through Apple's native messaging experience, with delivery status and supported media on compatible devices. iMessage shares the same reasoning engine and durable conversation model as other text channels. See [iMessage](/channels/imessage.md) for provisioning and phone line lifecycle. ### Voicemail Ringless voicemail that drops an audio message directly into a recipient's voicemail box without ringing the phone. This fits non-urgent outreach like appointment reminders and follow-up notifications, where a live conversation is not required. See [Voicemail](broken://pages/IBtMk6VVdepPtV2GWSAq) for delivery and status tracking. ### Email Transactional and marketing email delivery with verified sending domains. Each workspace configures sending domains with full DNS authentication - DKIM signatures, SPF records, DMARC policies, and inbound MX routing. Email use cases are typed as transactional (appointment confirmations, care instructions, lab results) or marketing (wellness campaigns, program enrollment), with tiered sending that starts conservatively and scales as the domain builds reputation. Email has its own send API and managed use-case configuration. Automations can invoke that supported path explicitly; email is not a target of the Conversations API's outbound-start or channel-switch operations. The platform tracks inbound replies and maintains thread continuity using standard message headers and stored references, while delivery, bounce, complaint, and unsubscribe status remain separate channel records. See [Email](/channels/email.md) for domain configuration, sending tiers, and thread continuity. ### Surfaces Web-based forms and data collection interfaces that the agent can introduce mid-conversation. When the agent needs structured input - a photo of an insurance card, a list of medications, a signed consent form - it generates a surface and shares its email or web link through a supported workflow. The patient completes it in a browser; the submission is stored immediately and can be projected into the world model asynchronously. See [Surfaces](/channels/surfaces.md) for how surfaces integrate with the conversation flow. ### Outbound Platform-initiated contact, where the agent reaches out first. Outbound calls, messaging workflows, triggers, and direct API requests each follow their supported channel contract. The conversation lifecycle API currently starts outbound SMS and iMessage threads and can switch an active thread between those two channels without losing history. See [Outbound](/channels/outbound.md) for starting conversations and switching channels mid-thread. ### Channel Availability Channel availability depends on workspace configuration, geography, provider capacity, and completed use-case provisioning. Voice setup can use Platform API resources where enabled. Email, SMS, iMessage, WhatsApp, and ringless voicemail can require Amigo-managed domain, carrier, number, or provider onboarding. Confirm the supported path for your workspace rather than inferring availability from a channel name in an API schema. ## Multi-Channel Orchestration A patient workflow can span multiple channels while retaining shared patient context. SMS and iMessage can preserve one durable conversation during an explicit channel switch. Voice calls, WhatsApp voice notes, and other transport-specific sessions keep their own conversation state while reading the same governed world-model context. Teams select channels through use cases, triggers, context graphs, and outbound policy. Patient preferences, consent, contact history, and the task should inform that configuration. Photos and document uploads use surface email or web links. Quick confirmations fit text, detailed materials fit email, and complex discussions often fit voice. ## Why This Matters for Healthcare Patients do not think in channels. They want their appointment scheduled, their prescription refilled, their referral processed. They do not want to be told "please call back during business hours" or "we can only handle that over the phone." A shared core lets teams reuse agent and Context Graph definitions instead of building an unrelated bot for every transport. Channel-specific tool eligibility, consent, delivery, operator controls, session state, and audit evidence still need explicit validation. ## Learn More {% content-ref url="/pages/jyoxNhN4VGjrq9P6R26S" %} [Phone](/channels/voice.md) {% endcontent-ref %} {% content-ref url="/pages/F9G0lrxZA31mW1pawkgs" %} [Text Sessions](/channels/text-sessions.md) {% endcontent-ref %} {% content-ref url="/pages/L5QVsqZuFuZalMUMRMw8" %} [Surfaces](/channels/surfaces.md) {% endcontent-ref %} {% content-ref url="/pages/8yGbb8LE1sy3JeaS7UnI" %} [Outbound](/channels/outbound.md) {% endcontent-ref %} {% content-ref url="/pages/uirHtW6W7wkJL0eKBdYK" %} [Email](/channels/email.md) {% endcontent-ref %} {% content-ref url="/pages/06YznjcZmK794tiVzM7q" %} [SMS](/channels/sms.md) {% endcontent-ref %} {% content-ref url="/pages/SS3ZnjwCmfLJCyDs8hcQ" %} [WhatsApp](/channels/whatsapp.md) {% endcontent-ref %} {% content-ref url="/pages/c1iRKBkz9pUpCgeAnQTO" %} [iMessage](/channels/imessage.md) {% endcontent-ref %} {% content-ref url="/pages/IBtMk6VVdepPtV2GWSAq" %} [Broken mention](broken://pages/IBtMk6VVdepPtV2GWSAq) {% 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/conversations.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.