Skip to main content
A phone call is live and turn by turn. Keep each turn short, recover from misheard values, and say what every yes will do. A caller can’t scan a screen. They may be distracted, in a noisy place, or unsure what the system needs. Speak the essential answer first, ask one question at a time, and give the caller a clear way to correct, pause, or reach a person. For channel setup steps, see Voice channels. To test the result, see Test voice agents.

Write for the channel

Design the words before you choose speech settings. Read the script aloud. If the meaning depends on punctuation, a screen, or a long list, revise the interaction. The same agents answer on every channel (Project → Operate → Deployments → Channels). Each channel shows what it supports and falls back to plain text. Write a template’s DEFAULT first, as a complete sentence that ends with the question. Give each button a VALUE a person would say, because routing reads it as the user’s message. Cross-channel recall needs a verified identity and recorded consent. Consent collection is on by default, so check the project’s Omnichannel settings and test with the identity and consent state your channel supplies.

Choose Pipeline Voice or Realtime LLM Voice

Set up voice channels at Project → Operate → Deployments → Channels → Voice. Choose from your targets sheet, then confirm the choice with an eval comparison. On a realtime line, set Realtime orchestration on the channel’s Speech tab. The mode applies to every agent a call can reach.
  • Runtime owned runs each caller turn through the runtime, so FLOW steps, tool contracts, and confirmations work as in chat.
  • Runtime guarded protects FLOW steps only. A reasoning agent’s tools run whenever the model calls them, within their contracts.
  • Never leave a line on Legacy.
Voyager runs Pipeline Voice, because Manage Trip waits for exact answers such as a booking reference or “refund or credit”. To compare lines, copy the voice scenarios once per line, because each scenario names its connection. Keep personas and evaluators the same, and record the provider, model, and mode.

Keep one agent with a phone behavior profile

Keep one agent for chat and voice. Put the spoken style in a behavior profile (Project → Settings → Agent Behavior → Behavior Profiles), and attach it to every agent with USE BEHAVIOR_PROFILE. Split an agent only when the phone conversation itself differs, such as an outbound call script or a keypad menu.
ABL: voice behavior profile
Use channel.name in the condition. A context.channel condition never matches, and the profile then does nothing. Check the channel name on a real test session (Project → Operate → Sessions), and list every voice transport you use. Studio’s test chat is web_debug, so test a profile on its own channel.
See Behavior profiles.

Write a voice script

Read the script aloud before you build. It shows unclear prompts, missing ways out, awkward read-outs, and promises the agent can’t keep. A transcript that looks clear can still be hard to hear at the actual pace. Every yes or no question names the action or choice it controls. “Would you like me to continue?” is too vague before a write. State what will change, then wait for an unambiguous answer. Script checks:
  • One question at the end of each turn.
  • Say what yes means before an action.
  • Read back reference codes and amounts when accuracy matters.
  • Don’t introduce details the system didn’t return.
  • Offer a way out, a correction, or a person.

Handle speech recognition errors

Speech recognition is less reliable for short codes, names, airport abbreviations, dates, and values spoken in noise. Build a recognition set from the fields the journey collects. Include likely accents, background conditions, words that sound alike, pauses, and corrections. When a value matters, read it back in words the caller can check. Let the caller correct one field without restarting the whole journey. Minimum STT confidence is off by default. Calibrate it on test calls before you raise it, because a low-confidence transcript counts as silence. If validation fails repeatedly, offer the keypad for digits, or a person.

Set listening time per question

On Pipeline Voice, set how long the recognizer waits after a pause with end_of_speech_turn_type in the step’s VOICE: block. end_of_speech_timeout_ms sets an exact wait from 100 to 5,000 ms. The most specific setting wins: a RESPOND’s VOICE, then the FLOW step, then the behavior profile, then the agent’s EXECUTION.voice.

Shape spoken output

Use short sentences, natural word order, and familiar terms. Avoid long lists, screen directions, internal agent names, raw tool output, and visual markup. Put the most important information before the explanation. Render codes and numbers for speech on purpose. A flight code can be easier as characters; a time is clearer in ordinary spoken form. Read amounts with units, and say the time zone when it matters. The phone profile shapes only what the model writes. RESPOND, template, and GATHER prompt text is spoken word for word, so give it a spoken version with VOICE: PLAIN_TEXT:; chat keeps the original. Studio’s debug chat is a text channel and never applies the phone profile, so hear the wording on a test call. Don’t read every search result. Offer two options, then ask which one. If a result is too complex to hear safely, offer to text it, and still say the essentials on the call, because the message may never be opened. The platform adds its own spoken-style rules on every voice turn: plain sentences, no markdown, no emoji, and no lists. What you write changes them.

Handle interruptions, silence, and recovery

Let callers interrupt ordinary explanations. Protect the few outputs that must be heard in full, such as a legal disclosure or a read-back right before a write. If a caller interrupts, stop speaking, recognize the new request, and keep the prior action uncommitted until confirmation is complete. Protect an output with BARGE_IN: disallow in its VOICE: block, and add STREAMING: false for one complete playback. STREAMING: false alone protects nothing. Keep the channel switch Allow caller to interrupt the welcome off to protect the greeting. It is off for new channels, so check older ones. Keep a pending action separate from a completed one. If the caller hangs up before confirming, don’t treat the earlier choice as a yes. An interruption during a write leads to a status check before any retry. See General settings for the runtime voice settings.

Plan transfers, outbound calls, and follow-ups

Before a transfer, tell the caller what happens next. The model never chooses where a call goes. Destinations come from Project → Settings → Agent Behavior → Agent Transfer, or from an ESCALATE routing entry.
  • Route phone escalations with WHEN: system.isVoice == true. system.channel == "voice" misses Twilio and AudioCodes calls.
  • Put session values such as {{booking_ref}} under metadata:. Values under sip_headers: are sent as literal text.
  • Turn on Send Conversation Summary in SIP Header, so the person doesn’t ask again. Don’t send secrets or unnecessary personal data.
  • If a transfer fails, the call stays with the agent. Write words for that path, and test it.
See the Outbound calls API and Agent behavior settings.