> 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/voice.md).

# Phone

Phone has real-time constraints that asynchronous text does not: callers expect a prompt response, silence can feel like a failure, and vocal delivery affects the interaction. Voice shares the platform's reasoning and Context Graph concepts, while transport, tool exposure, safety controls, and lifecycle behavior still depend on the selected runtime and channel configuration. See [Agent Architecture](/agent/reasoning-engine.md).

## Conference-First Architecture

Platform-managed phone calls use a multi-party conference for the caller and agent legs. This design lets an authorized human [operator](/operations-and-safety/operators.md) join a supported call as another participant without replacing the caller's connection.

For outbound calls, session preparation can begin while the destination is ringing. For inbound calls, the conference can hold the caller while the session and greeting become ready, then add the agent leg. These readiness paths reduce first-audio delay, but telephony and dependency latency can still affect when the greeting begins.

When an operator joins, they enter the same conference in a supported listen or takeover mode. Operator access is permission-gated, and the exact join method depends on the configured operator channel.

```mermaid
flowchart LR
    C[Caller] <-->|Audio| Conf[Conference]
    A[AI Agent] <-->|Audio| Conf
    O[Operator] -.->|Joins on\nescalation| Conf
```

## The Voice Pipeline

On the Amigo-managed speech pipeline, a supported call turn flows through five layers that convert caller audio into a spoken response. Layers 1-2 and 5 are voice-specific. Layers 3-4 use the shared [reasoning engine](/agent/reasoning-engine.md). A service configured for a separate realtime speech provider can follow that provider's audio and turn-processing path instead.

| Layer                          | What It Does                                                                                                                                                                                                                                                                                                                                                   | Scope  |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| **1. Audio Capture**           | Captures the caller's audio stream from the telephony layer. Sends it to two parallel processors: speech-to-text and emotion detection. Neither blocks the other.                                                                                                                                                                                              | Voice  |
| **2. Speech-to-Text**          | Converts audio to text using streaming transcription with domain-specific vocabulary boosting. Determines when the caller has finished speaking and emits final utterance signals.                                                                                                                                                                             | Voice  |
| **3. Intelligence**            | Maintains a short rolling emotional state from acoustic valence, arousal, categorical scores, transcript sentiment, and toxicity. A separate per-call acoustic profile is exposed for observability after warmup.                                                                                                                                              | Engine |
| **4. Navigation and Response** | The context graph engine selects the right action, chooses the appropriate vocal emotion for the response, generates text, and produces filler speech to cover processing time. A unified voice timeline orchestrator coordinates all filler emission, empathy pauses, and tool progress updates through a signal-driven model rather than independent timers. | Engine |
| **5. Text-to-Speech**          | Converts the generated text into spoken audio using the emotion selected during navigation, along with pace and emphasis. Each utterance carries its own TTS parameters (emotion and speed), so fillers and responses can use different vocal qualities without interference. Streams audio back to the caller through the conference.                         | Voice  |

If the navigation model times out or its configured identifier is unavailable, the engine can try a configured fallback model. Voice filler may cover part of that delay. If no fallback succeeds, navigation remains in the current engageable state rather than claiming that the turn advanced.

After the call ends, optional background jobs can verify the caller transcript and score the interaction across quality dimensions when recording and analysis are enabled. Accuracy evidence and suggested keyterms are review inputs; they do not update transcription configuration automatically.

## Patient Context Injection

When a call connects, the agent can use the caller's phone number to look up an existing workspace entity. If a matching entity and authorized data are available, selected demographics and clinical or operational context can be included in the session. Unknown callers and incomplete source data are valid outcomes and must not be treated as identity verification.

The runtime can refresh session context after supported writes, but connector projections and external systems may be eventually consistent. Agents should verify time-sensitive facts through the appropriate source rather than assume every write is immediately visible everywhere.

## Session Event Injection

External systems can inject events into active voice sessions in real time. The agent processes injected events through its response generation and speaks a natural response.

| Type               | Behavior                     | Use Case                                                            |
| ------------------ | ---------------------------- | ------------------------------------------------------------------- |
| **External event** | Queues behind current speech | EHR notifications, appointment confirmations, system status updates |
| **Guidance**       | Interrupts current speech    | Operator steering, real-time instructions to the agent              |

Events can be injected through multiple paths: an HTTP endpoint, a WebSocket control channel, or through the platform API. The platform API also provides a dedicated [operator guidance](/operations-and-safety/operators.md) endpoint so operators can send guidance scoped to their identity and permissions.

The injection path supports multi-instance deployments by relaying commands to the session owner. Delivery and reconnection are still subject to session state, authorization, network conditions, and the lifecycle of the active call.

## Operational Impact

For healthcare organizations, voice agents can augment front-desk workflows such as scheduling, benefits intake, refill-request collection, and general inquiries. The actions available in a specific deployment depend on the configured context graph, tools, integrations, permissions, and safety controls. Supported workflows can route or escalate to a human operator.

Calls emit lifecycle and conversation data to the [world model](/data/world-model.md). Conversation-derived observations remain source-attributed and are evaluated by outbound source, confidence, schema, and destination policies before any eligible external write. Automated delivery outcomes are reported separately and are not treated as confirmed when a destination call fails. Review-gated external write proposals are a separate private-preview path for configured mutations.

## Phone Numbers

Phone numbers are the entry point for inbound calls. Each number is provisioned through the platform and routed to a specific service.

### Provisioning and Lifecycle

Numbers follow a four-step lifecycle: **search** provider inventory, **purchase** an eligible number, **assign** it to a use case or service, and **release** it when no longer needed. Multiple numbers can route to the same service - for example, different clinic locations sharing one scheduling agent.

Four number types are represented by the provisioning API. Inventory varies by country and provider:

| Type          | Use Case                                                  |
| ------------- | --------------------------------------------------------- |
| **Local**     | Geographic numbers tied to a specific area code or region |
| **Mobile**    | Mobile numbers, common in markets outside North America   |
| **Toll-free** | Free-to-caller numbers for national reach                 |
| **National**  | Non-geographic national numbers in supported countries    |

Search can filter by country, type, required capabilities, and - for local numbers - area code. An empty result means no matching inventory was returned; it does not guarantee that a type is permanently unavailable in that country.

### Channel Management

Phone-number provisioning is gated by an approved business profile and any compliance bundle required for the requested country, number type, and business use. Requirements are conditional; not every number is eligible for the same voice-branding or messaging programs.

For US voice numbers, caller-authentication enrollment applies to supported local and toll-free numbers. Display-name registration applies to eligible US standard long-code numbers, not US toll-free or Canadian numbers. Other countries can require provider-defined regulatory bundles and supporting documents. The platform resolves the applicable bundle before purchase and blocks provisioning until required approvals are present.

Messaging compliance is separate from voice provisioning. US long-code application-to-person messaging uses a brand-and-campaign flow, while US and Canadian toll-free messaging uses toll-free verification. A number having SMS capability does not mean it is approved for every messaging use case.

Some inventory requires a local, foreign, or other approved address. Search excludes numbers the setup cannot satisfy where possible, and purchase validates the stored business address against the selected number's requirement.

The number-purchase operation compensates for provider-side changes when a later step in that purchase fails. Compliance submissions have their own asynchronous review states and may require corrected information or resubmission. Approval or registration does not guarantee a particular carrier display, attestation treatment, answer rate, or spam-classification outcome.

### Routing

When a call arrives on a provisioned number, the platform routes it to the service associated with that number. The service association determines:

* Which context graph governs the conversation flow
* Which voice settings (tone, speed, key terms) apply
* Which world model workspace provides patient context
* Which escalation rules and authored safety instructions or guardrails apply

Each phone number routes to exactly one service. This keeps the mapping simple - if you need to know what a number does, look at its service assignment.

{% hint style="info" %}
**Developer Guide** - For phone number API endpoints and voice agent integration details, see the [Developer Guide](https://docs.amigo.ai/developer-guide/platform-api/conversations/voice-agent).
{% endhint %}

## Learn More

{% content-ref url="/pages/diNa7vR8bPyfaSkKqKHe" %}
[Audio Pipeline](/channels/voice/audio-pipeline.md)
{% endcontent-ref %}

{% content-ref url="/pages/aYU0aijmZffitKIRNaTq" %}
[Emotion Detection](/channels/voice/emotion-detection.md)
{% endcontent-ref %}

{% content-ref url="/pages/IeSDYAEqjzKUcXkDFduG" %}
[Compound Emotions](/channels/voice/compound-emotions.md)
{% endcontent-ref %}

{% content-ref url="/pages/nRAlEc8vAwxClF3hhQFs" %}
[Call Recordings](/channels/voice/recordings.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/voice.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.