docs/plugins/voice-call.md
Voice calls for OpenClaw via a plugin. Supports outbound notifications, multi-turn conversations, full-duplex realtime voice, streaming transcription, and inbound calls with allowlist policies.
Current providers: twilio (Programmable Voice + Media Streams),
telnyx (Call Control v2), plivo (Voice API + XML transfer + GetInput
speech), mock (dev/no network).
Use the bare package to follow the current official release tag. Pin an
exact version only when you need a reproducible install.
Restart the Gateway afterwards so the plugin loads.
The default output is readable in chat logs and terminals. It checks
plugin enablement, provider credentials, webhook exposure, and that
only one audio mode (`streaming` or `realtime`) is active. Use
`--json` for scripts.
Both are dry runs by default. Add `--yes` to actually place a short
outbound notify call:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
```
If enabled: true but the selected provider is missing credentials,
Gateway startup logs a setup-incomplete warning with the missing keys and
skips starting the runtime. Commands, RPC calls, and agent tools still
return the exact missing provider configuration when used.
{
plugins: {
entries: {
"voice-call": {
enabled: true,
config: {
provider: "twilio", // or "telnyx" | "plivo" | "mock"
fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
toNumber: "+15550005678",
sessionScope: "per-phone", // per-phone | per-call
numbers: {
"+15550009999": {
inboundGreeting: "Silver Fox Cards, how can I help?",
responseSystemPrompt: "You are a concise baseball card specialist.",
tts: {
providers: {
openai: { voice: "alloy" },
},
},
},
},
twilio: {
accountSid: "ACxxxxxxxx",
authToken: "...",
},
telnyx: {
apiKey: "...",
connectionId: "...",
// Telnyx webhook public key from the Mission Control Portal
// (Base64; can also be set via TELNYX_PUBLIC_KEY).
publicKey: "...",
},
plivo: {
authId: "MAxxxxxxxxxxxxxxxxxxxx",
authToken: "...",
},
// Webhook server
serve: {
port: 3334,
path: "/voice/webhook",
},
// Webhook security (recommended for tunnels/proxies)
webhookSecurity: {
allowedHosts: ["voice.example.com"],
trustedProxyIPs: ["100.64.0.1"],
},
// Public exposure (pick one)
// publicUrl: "https://example.ngrok.app/voice/webhook",
// tunnel: { provider: "ngrok" },
// tailscale: { mode: "funnel", path: "/voice/webhook" },
outbound: {
defaultMode: "notify", // notify | conversation
},
streaming: { enabled: true /* see Streaming transcription */ },
realtime: { enabled: false /* see Realtime voice */ },
},
},
},
},
}
Auto-migrated streaming keys:
- `streaming.sttProvider` → `streaming.provider`
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
- `streaming.sttModel` → `streaming.providers.openai.model`
- `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs`
- `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold`
By default, Voice Call uses sessionScope: "per-phone" so repeat calls from
the same caller keep conversation memory. Set sessionScope: "per-call" when
each carrier call should start with fresh context, for example reception,
booking, IVR, or Google Meet bridge flows where the same phone number may
represent different meetings.
realtime selects a full-duplex realtime voice provider for live call
audio. It is separate from streaming, which only forwards audio to
realtime transcription providers.
Current runtime behaviour:
realtime.enabled is supported for Twilio Media Streams.realtime.provider is optional. If unset, Voice Call uses the first registered realtime voice provider.google) and OpenAI (openai), registered by their provider plugins.realtime.providers.<providerId>.openclaw_agent_consult realtime tool by default. The realtime model can call it when the caller asks for deeper reasoning, current information, or normal OpenClaw tools.realtime.fastContext.enabled is default-off. When enabled, Voice Call first searches indexed memory/session context for the consult question and returns those snippets to the realtime model within realtime.fastContext.timeoutMs before falling back to the full consult agent only if realtime.fastContext.fallbackToConsult is true.realtime.provider points at an unregistered provider, or no realtime voice provider is registered at all, Voice Call logs a warning and skips realtime media instead of failing the whole plugin.sessionScope (per-phone by default, or per-call for isolated calls).realtime.toolPolicy controls the consult run:
| Policy | Behavior |
|---|---|
safe-read-only | Expose the consult tool and limit the regular agent to read, web_search, web_fetch, x_search, memory_search, and memory_get. |
owner | Expose the consult tool and let the regular agent use the normal agent tool policy. |
none | Do not expose the consult tool. Custom realtime.tools are still passed through to the realtime provider. |
```json5
{
plugins: {
entries: {
"voice-call": {
config: {
provider: "twilio",
inboundPolicy: "allowlist",
allowFrom: ["+15550005678"],
realtime: {
enabled: true,
provider: "google",
instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
toolPolicy: "safe-read-only",
providers: {
google: {
apiKey: "${GEMINI_API_KEY}",
model: "gemini-2.5-flash-native-audio-preview-12-2025",
voice: "Kore",
silenceDurationMs: 500,
startSensitivity: "high",
},
},
},
},
},
},
},
}
```
See Google provider and OpenAI provider for provider-specific realtime voice options.
streaming selects a realtime transcription provider for live call audio.
Current runtime behavior:
streaming.provider is optional. If unset, Voice Call uses the first registered realtime transcription provider.deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai), and xAI (xai), registered by their provider plugins.streaming.providers.<providerId>.start message, Voice Call registers the stream immediately, queues inbound media through the transcription provider while the provider connects, and starts the initial greeting only after realtime transcription is ready.streaming.provider points at an unregistered provider, or none is registered, Voice Call logs a warning and skips media streaming instead of failing the whole plugin.```json5
{
plugins: {
entries: {
"voice-call": {
config: {
streaming: {
enabled: true,
provider: "openai",
streamPath: "/voice/stream",
providers: {
openai: {
apiKey: "sk-...", // optional if OPENAI_API_KEY is set
model: "gpt-4o-transcribe",
silenceDurationMs: 800,
vadThreshold: 0.5,
},
},
},
},
},
},
},
}
```
```json5
{
plugins: {
entries: {
"voice-call": {
config: {
streaming: {
enabled: true,
provider: "xai",
streamPath: "/voice/stream",
providers: {
xai: {
apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
endpointingMs: 800,
language: "en",
},
},
},
},
},
},
},
}
```
Voice Call uses the core messages.tts configuration for streaming
speech on calls. You can override it under the plugin config with the
same shape — it deep-merges with messages.tts.
{
tts: {
provider: "elevenlabs",
providers: {
elevenlabs: {
voiceId: "pMsXgVXv3BLzUgSXRplE",
modelId: "eleven_multilingual_v2",
},
},
},
}
Behavior notes:
tts.<provider> keys inside plugin config (openai, elevenlabs, microsoft, edge) are repaired by openclaw doctor --fix; committed config should use tts.providers.<provider>.<Say>. If telephony TTS is unavailable in that state, the playback request fails instead of mixing two playback paths.from, to, attempts) for debugging.Inbound policy defaults to disabled. To enable inbound calls, set:
{
inboundPolicy: "allowlist",
allowFrom: ["+15550001234"],
inboundGreeting: "Hello! How can I help?",
}
Auto-responses use the agent system. Tune with responseModel,
responseSystemPrompt, and responseTimeoutMs.
Use numbers when one Voice Call plugin receives calls for multiple phone
numbers and each number should behave like a different line. For example, one
number can use a casual personal assistant while another uses a business
persona, a different response agent, and a different TTS voice.
Routes are selected from the provider-supplied dialed To number. Keys must be
E.164 numbers. When a call arrives, Voice Call resolves the matching route once,
stores the matched route on the call record, and reuses that effective config
for the greeting, classic auto-response path, realtime consult path, and TTS
playback. If no route matches, the global Voice Call config is used.
Outbound calls do not use numbers; pass the outbound target, message, and
session explicitly when initiating the call.
Route overrides currently support:
inboundGreetingttsagentIdresponseModelresponseSystemPromptresponseTimeoutMsThe tts route value deep-merges over the global Voice Call tts config, so
you can usually override only the provider voice:
{
inboundGreeting: "Hello from the main line.",
responseSystemPrompt: "You are the default voice assistant.",
tts: {
provider: "openai",
providers: {
openai: { voice: "coral" },
},
},
numbers: {
"+15550001111": {
inboundGreeting: "Silver Fox Cards, how can I help?",
responseSystemPrompt: "You are a concise baseball card specialist.",
tts: {
providers: {
openai: { voice: "alloy" },
},
},
},
},
}
For auto-responses, Voice Call appends a strict spoken-output contract to the system prompt:
{"spoken":"..."}
Voice Call extracts speech text defensively:
"spoken" keys.This keeps spoken playback focused on caller-facing text and avoids leaking planning text into audio.
For outbound conversation calls, first-message handling is tied to live
playback state:
listening and the initial message remains queued for retry.<Say> TwiML update for that initial message, so outbound <Connect><Stream> sessions stay attached.When a Twilio media stream disconnects, Voice Call waits 2000 ms before auto-ending the call:
Use staleCallReaperSeconds to end calls that never receive a terminal
webhook (for example, notify-mode calls that never complete). The default
is 0 (disabled).
Recommended ranges:
120–300 seconds for notify-style flows.maxDurationSeconds so normal calls can finish. A good starting point is maxDurationSeconds + 30–60 seconds.{
plugins: {
entries: {
"voice-call": {
config: {
maxDurationSeconds: 300,
staleCallReaperSeconds: 360,
},
},
},
},
}
When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the public URL for signature verification. These options control which forwarded headers are trusted:
<ParamField path="webhookSecurity.allowedHosts" type="string[]"> Allowlist hosts from forwarding headers. </ParamField> <ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean"> Trust forwarded headers without an allowlist. </ParamField> <ParamField path="webhookSecurity.trustedProxyIPs" type="string[]"> Only trust forwarded headers when the request remote IP matches the list. </ParamField>Additional protections:
<Gather> callbacks, so stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.Example with a stable public host:
{
plugins: {
entries: {
"voice-call": {
config: {
publicUrl: "https://voice.example.com/voice/webhook",
webhookSecurity: {
allowedHosts: ["voice.example.com"],
},
},
},
},
},
}
openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123" # alias for call
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall speak --call-id <id> --message "One moment"
openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall latency # summarize turn latency from logs
openclaw voicecall expose --mode funnel
When the Gateway is already running, operational voicecall commands delegate
to the Gateway-owned voice-call runtime so the CLI does not bind a second
webhook server. If no Gateway is reachable, the commands fall back to a
standalone CLI runtime.
latency reads calls.jsonl from the default voice-call storage path.
Use --file <path> to point at a different log and --last <n> to limit
analysis to the last N records (default 200). Output includes p50/p90/p99
for turn latency and listen-wait times.
Tool name: voice_call.
| Action | Args |
|---|---|
initiate_call | message, to?, mode?, dtmfSequence? |
continue_call | callId, message |
speak_to_user | callId, message |
send_dtmf | callId, digits |
end_call | callId |
get_status | callId |
This repo ships a matching skill doc at skills/voice-call/SKILL.md.
| Method | Args |
|---|---|
voicecall.initiate | to?, message, mode?, dtmfSequence? |
voicecall.continue | callId, message |
voicecall.speak | callId, message |
voicecall.dtmf | callId, digits |
voicecall.end | callId |
voicecall.status | callId |
dtmfSequence is only valid with mode: "conversation". Notify-mode calls
should use voicecall.dtmf after the call exists if they need post-connect
digits.
Run setup from the same environment that runs the Gateway:
openclaw voicecall setup
openclaw voicecall setup --json
For twilio, telnyx, and plivo, webhook-exposure must be green. A
configured publicUrl still fails when it points at local or private network
space, because the carrier cannot call back into those addresses. Do not use
localhost, 127.0.0.1, 0.0.0.0, 10.x, 172.16.x-172.31.x,
192.168.x, 169.254.x, fc00::/7, or fd00::/8 as publicUrl.
Twilio notify-mode outbound calls send their initial <Say> TwiML directly in
the create-call request, so the first spoken message does not depend on Twilio
fetching webhook TwiML. A public webhook is still required for status callbacks,
conversation calls, pre-connect DTMF, realtime streams, and post-connect call
control.
Use one public exposure path:
{
plugins: {
entries: {
"voice-call": {
config: {
publicUrl: "https://voice.example.com/voice/webhook",
// or
tunnel: { provider: "ngrok" },
// or
tailscale: { mode: "funnel", path: "/voice/webhook" },
},
},
},
},
}
After changing config, restart or reload the Gateway, then run:
openclaw voicecall setup
openclaw voicecall smoke
voicecall smoke is a dry run unless you pass --yes.
Check the selected provider and the required credential fields:
twilio.accountSid, twilio.authToken, and fromNumber, or
TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_FROM_NUMBER.telnyx.apiKey, telnyx.connectionId, telnyx.publicKey, and
fromNumber.plivo.authId, plivo.authToken, and fromNumber.Credentials must exist on the Gateway host. Editing a local shell profile does not affect an already running Gateway until it restarts or reloads its environment.
Confirm the provider console points at the exact public webhook URL:
https://voice.example.com/voice/webhook
Then inspect runtime state:
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw logs --follow
Common causes:
publicUrl points at a different path than serve.path.When a reverse proxy or tunnel is in front of the Gateway, set
webhookSecurity.allowedHosts to the public hostname, or use
webhookSecurity.trustedProxyIPs for a known proxy address. Use
webhookSecurity.trustForwardingHeaders only when the proxy boundary is under
your control.
Provider signatures are checked against the public URL OpenClaw reconstructs from the incoming request. If signatures fail:
publicUrl, including
scheme, host, and path.publicUrl when the tunnel hostname changes.webhookSecurity.allowedHosts.skipSignatureVerification outside local testing.Google Meet uses this plugin for Twilio dial-in joins. First verify Voice Call:
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
Then verify the Google Meet transport explicitly:
openclaw googlemeet setup --transport twilio
If Voice Call is green but the Meet participant never joins, check the Meet
dial-in number, PIN, and --dtmf-sequence. The phone call can be healthy while
the meeting rejects or ignores an incorrect DTMF sequence.
Google Meet passes the Meet DTMF sequence and intro text to voicecall.start.
For Twilio calls, Voice Call serves the DTMF TwiML first, redirects back to the
webhook, then opens the realtime media stream so the saved intro is generated
after the phone participant has joined the meeting.
Use openclaw logs --follow for the live phase trace. A healthy Twilio Meet
join logs this order:
openclaw voicecall tail still shows persisted call records; it is useful for
call state and transcripts, but not every webhook/realtime transition appears
there.
Confirm only one audio mode is enabled. realtime.enabled and
streaming.enabled cannot both be true.
For realtime Twilio calls, also verify:
realtime.provider is unset or names a registered provider.openclaw logs --follow shows realtime TwiML served, the realtime bridge
started, and the initial greeting queued.