> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/channels/voice.md). # Phone Real-time phone-based conversations with conference-first architecture, emotion detection, and adaptive voice delivery. 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, the runtime prepares the first agent audio and joins the agent before it dials the callee, and the agent speaks only once the callee answers. A voicemail that picks up counts as an answer. 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 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 %%{init: {"theme":"base","fontFamily":"Inter, sans-serif","themeVariables":{"fontFamily":"Inter, sans-serif","fontSize":"16px","background":"#FAF8F6","primaryColor":"#F1EAE7","primaryTextColor":"#1A1817","primaryBorderColor":"#D7D2D0","secondaryColor":"#FDFCFB","tertiaryColor":"#F6F2F0","lineColor":"#575452","textColor":"#3D3937","clusterBkg":"#FDFCFB","clusterBorder":"#E8E2DF","edgeLabelBackground":"#FAF8F6","actorBkg":"#F1EAE7","actorTextColor":"#1A1817","actorBorder":"#D7D2D0","actorLineColor":"#575452","signalColor":"#575452","signalTextColor":"#3D3937","labelBoxBkgColor":"#F1EAE7","labelBoxBorderColor":"#D7D2D0","labelTextColor":"#3D3937","loopTextColor":"#3D3937","noteBkgColor":"#F6F2F0","noteBorderColor":"#D7D2D0","noteTextColor":"#3D3937","activationBkgColor":"#F1EAE7","activationBorderColor":"#D7D2D0","altSectionBkgColor":"#FAF8F6","altSectionColor":"#3D3937"}}}%% flowchart LR C[Caller] <-->|Audio| Conf[Conference] A[AI Agent] <-->|Audio| Conf O[Operator] -.->|Joins on
escalation| Conf ``` ## Call Opening Platform-managed and `gpt_realtime` calls open with an AI and recording notice. On the platform-managed runtime, caller speech does not cut it off. See [Call Opening](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent#call-opening) for the wording, its languages, and when it plays on each runtime. ## The Voice Pipeline On the Concurrence-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 navigation fails or runs out of time, the agent stays in its current state and answers from there rather than claiming that the turn advanced. Voice filler may cover part of that delay. When the call ends, the platform-managed runtime records a summary of the call's operational signals. The platform does not re-transcribe the call or score transcript accuracy afterward; trace analysis, judges, and production evals are configured separately and have their own prerequisites. The separate realtime-provider runtime builds workflow instructions from a Context Graph with exactly one action state. That state's objective, action descriptions, and guidelines become instructions for the provider's model. A save that would run this runtime on any other graph is refused with `422`; see [Session Provider](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services#session-provider). If instruction preparation fails, the call can continue with fallback instructions, so a connected call does not prove the intended workflow loaded. Multi-state navigation, operator takeover, and session event injection from the platform-managed pipeline do not carry over to this runtime. Validate the intended workflow and escalation path on the selected runtime before launch. The `gpt_realtime` path also retains completed transcripts and tool calls in conversation order, with incremental writes and a completion retry. Missing completions or persistence failures can leave gaps. Retained history, live observer events, recordings, and post-call quality analysis are separate evidence; see [Call Record and Persistence](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent#call-record-and-persistence). ## Patient Context Injection When a call connects, the agent can use the caller's phone number to find a matching workspace record, and a session can also open with an `entity_id`. Either way the caller starts unverified: the agent knows a record may match but sees none of its details until the caller states a full name and date of birth that match exactly one record through `world_confirm_patient_identity`.
A caller matched by phone number or entity_id starts unverified, and built-in patient reads return verification_required. A full name and date of birth that match one record load the patient context, and repeated failures lock verification for the conversation.

A phone number match points to a candidate record. It is not proof of who is speaking.

Unknown callers and incomplete source data are valid outcomes. See [Caller Verification](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent#caller-verification) for what record reads return before and after verification, the sessions that aren't gated, and how to add verification to a Context Graph. Valid inbound phone numbers are normalized to E.164. Withheld, anonymous, invalid, and non-phone caller identifiers provide no phone identity for lookup or automatic channel-context filling. A valid number alone is not proof of who is speaking. The runtime can refresh session context after supported writes, but 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 supported platform-managed voice sessions in real time. When delivery and response generation succeed, the agent can speak a response. The separate realtime-provider runtime does not process these injections. | 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 stay in the world model. A change to an external system happens through an integration tool the agent calls, and the call's result is the evidence of what the destination accepted. ## 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.concurrence.com/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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.concurrence.com/channels/voice.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.