Voice Call (plugin)
Voice calls for WednesdayAI via a bundled plugin. It supports outbound notifications and multi-turn conversations with inbound policies. Current providers:twilio(Programmable Voice + Media Streams)telnyx(Call Control v2)plivo(Voice API + XML transfer + GetInput speech)mock(dev/no network)
- Enable the bundled plugin
- Restart Gateway
- Configure under
plugins.entries.voice-call.config - Use
wednesdayai voicecall ...or thevoice_calltool
Where it runs (local vs remote)
The Voice Call plugin runs inside the Gateway process. If you use a remote Gateway, configure the plugin on the machine running the Gateway, then restart that Gateway.Enable the bundled plugin
WednesdayAI ships Voice Call as a bundled extension. Enable that copy rather than installing a duplicate managed package:Origin: bundled. Restart the Gateway afterwards. On Linux, run
systemctl --user restart openclaw-gateway; on macOS, run
wednesdayai gateway restart --deep.
Plugin configuration and environment-variable changes also require a Gateway restart; Voice
Call does not hot-reload them into the running plugin.
Development copy
Only use a managed local copy when developing a separate plugin build:plugins.load.paths.
Config
Set config underplugins.entries.voice-call.config:
- Twilio/Telnyx require a publicly reachable webhook URL.
- Plivo requires a publicly reachable webhook URL.
mockis a local dev provider (no network calls).- Telnyx requires
telnyx.publicKey(orTELNYX_PUBLIC_KEY) unlessskipSignatureVerificationis true. skipSignatureVerificationis for local testing only.- If you use ngrok free tier, set
publicUrlto the exact ngrok URL; signature verification is always enforced. tunnel.allowNgrokFreeTierLoopbackBypass: trueallows Twilio webhooks with invalid signatures only whentunnel.provider="ngrok"andserve.bindis loopback (ngrok local agent). Use for local dev only.- Ngrok free tier URLs can change or add interstitial behavior; if
publicUrldrifts, Twilio signatures will fail. For production, prefer a stable domain or Tailscale funnel. - Streaming security defaults:
streaming.preStartTimeoutMsdefaults to5000and closes sockets that never send a validstartframe.streaming.maxPendingConnectionsdefaults to32unauthenticated pre-start sockets.streaming.maxPendingConnectionsPerIpdefaults to4per source IP.streaming.maxConnectionsdefaults to128total pending and active sockets.- Source-IP limits use the socket peer address. Behind a reverse proxy, that may be the proxy address.
Stale call reaper
UsestaleCallReaperSeconds to end calls that never receive a terminal webhook
(for example, notify-mode calls that never complete). The default is 0
(disabled).
Recommended ranges:
- Production:
120–300seconds for notify-style flows. - Keep this value higher than
maxDurationSecondsso normal calls can finish. A good starting point ismaxDurationSeconds + 30–60seconds.
Webhook security
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.webhookSecurity.allowedHosts allowlists hosts from forwarding headers.
webhookSecurity.trustForwardingHeaders trusts forwarded headers without an allowlist.
webhookSecurity.trustedProxyIPs only trusts forwarded headers when the request
remote IP matches the list.
webhookSecurity.allowedHosts and trustedProxyIPs default to empty lists;
trustForwardingHeaders defaults to false.
Webhook replay protection is enabled for Twilio and Plivo. Replayed valid webhook
requests are acknowledged but skipped for side effects.
Twilio conversation turns include a per-turn token in <Gather> callbacks, so
stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
Example with a stable public host:
TTS for calls
Voice Call uses the coremessages.tts configuration (OpenAI or ElevenLabs) for
streaming speech on calls. You can override it under the plugin config with the
same shape — it deep‑merges with messages.tts.
- Edge TTS is ignored for voice calls (telephony audio needs PCM; Edge output is unreliable).
- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
Streaming VAD and interruption
Streaming defaults to disabled. When enabled, OpenAI STT uses modelgpt-4o-transcribe, server VAD threshold 0.5,
fixed prefix padding 300 ms, and silenceDurationMs 800 ms. These telephony defaults
are separate from the OpenAI Realtime Talk defaults (threshold 0.5, prefix padding
300 ms, silence duration 500 ms — see Talk realtime voice and
Realtime Voice gateway relay). Voice Call’s
silenceDurationMs 800 ms is not affected by the Talk preset — the two paths are
configured independently.
Media-stream speech-start detection and the resulting response-abort/barge-in path are
currently Twilio-only: Twilio’s media stream WebSocket carries a real-time VAD
speech-start event, which aborts the in-flight response generation and clears the
in-flight TTS audio from Twilio’s playback buffer over the Media Streams clear
control frame. Telnyx and Plivo do not open a media-stream WebSocket on this path, so
they currently have no media-stream speech-start/barge-in path and no equivalent
mid-response interruption. A later generation owns a separate lifecycle, so stale
audio or transcript output from an aborted Twilio response is not delivered.
The streaming configuration exposes only the existing VAD hint fields
streaming.vadThreshold and streaming.silenceDurationMs; the UI may display these
as advanced tuning hints. Prefix padding is fixed at 300 ms for this telephony path
and is not configurable.
The STT connection enforces these hard limits:
- 16 MiB maximum inbound provider frame.
- 1 MiB maximum buffered outbound send data.
- 10-second connection timeout.
- Five reconnect attempts with exponential backoff.
OPENAI_API_KEY, the STT model, and network
access before debugging TTS. Restart after changing the key.
More examples
Use core TTS only (no override):Inbound calls
Inbound policy defaults todisabled.
To enable allowlisted inbound calls, set:
responseModelresponseSystemPromptresponseTimeoutMs
CLI
Agent tool
Tool name:voice_call
Actions:
initiate_call(message, to?, mode?)continue_call(callId, message)speak_to_user(callId, message)end_call(callId)get_status(callId)
skills/voice-call/SKILL.md.
Gateway RPC
voicecall.initiate(to?,message,mode?)voicecall.continue(callId,message)voicecall.speak(callId,message)voicecall.end(callId)voicecall.status(callId)