@openclaw/voice-call 2026.3.12 → 2026.5.1-beta.1

package/README.md

@@ -25,9 +25,10 @@ Restart the Gateway afterwards.
 ### Option B: copy into your global extensions folder (dev)
 
 ```bash
-mkdir -p ~/.openclaw/extensions
-cp -R extensions/voice-call ~/.openclaw/extensions/voice-call
-cd ~/.openclaw/extensions/voice-call && pnpm install
+PLUGIN_HOME=~/.openclaw/extensions
+mkdir -p "$PLUGIN_HOME"
+cp -R <local-plugin-checkout> "$PLUGIN_HOME/voice-call"
+cd "$PLUGIN_HOME/voice-call" && pnpm install
 ```
 
 ## Config
@@ -73,9 +74,20 @@ Put under `plugins.entries.voice-call.config`:
     defaultMode: "notify", // or "conversation"
   },
 
+  // Optional response agent workspace. Defaults to "main".
+  agentId: "main",
+
   streaming: {
     enabled: true,
+    // optional; if omitted, Voice Call picks the first registered
+    // realtime-transcription provider by autoSelectOrder
+    provider: "<realtime-transcription-provider-id>",
     streamPath: "/voice/stream",
+    providers: {
+      "<realtime-transcription-provider-id>": {
+        // provider-owned options
+      },
+    },
     preStartTimeoutMs: 5000,
     maxPendingConnections: 32,
     maxPendingConnectionsPerIp: 4,
@@ -89,56 +101,20 @@ Notes:
 - Twilio/Telnyx/Plivo require a **publicly reachable** webhook URL.
 - `mock` is a local dev provider (no network calls).
 - Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
-- `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Use for local dev only.
-
-Streaming security defaults:
-
-- `streaming.preStartTimeoutMs` closes sockets that never send a valid `start` frame.
-- `streaming.maxPendingConnections` caps total unauthenticated pre-start sockets.
-- `streaming.maxPendingConnectionsPerIp` caps unauthenticated pre-start sockets per source IP.
-- `streaming.maxConnections` caps total open media stream sockets (pending + active).
+- If older configs still use `provider: "log"`, `twilio.from`, or legacy `streaming.*` OpenAI keys, run `openclaw doctor --fix` to rewrite them.
+- advanced webhook, streaming, and tunnel notes: `https://docs.openclaw.ai/plugins/voice-call`
+- `responseModel` is optional. When unset, voice responses use the runtime default model.
 
 ## Stale call reaper
 
-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:
-
-- **Production:** `120`–`300` seconds for notify-style flows.
-- Keep this value **higher than `maxDurationSeconds`** so normal calls can
-  finish. A good starting point is `maxDurationSeconds + 30–60` seconds.
-
-Example:
-
-```json5
-{
-  staleCallReaperSeconds: 360,
-}
-```
+See the plugin docs for recommended ranges and production examples:
+`https://docs.openclaw.ai/plugins/voice-call#stale-call-reaper`
 
 ## TTS for calls
 
-Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
-streaming speech on calls. You can override it under the plugin config with the
-same shape — overrides deep-merge with `messages.tts`.
-
-```json5
-{
-  tts: {
-    provider: "openai",
-    openai: {
-      voice: "alloy",
-    },
-  },
-}
-```
-
-Notes:
-
-- 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.
+Voice Call uses the core `messages.tts` configuration for
+streaming speech on calls. Override examples and provider caveats live here:
+`https://docs.openclaw.ai/plugins/voice-call#tts-for-calls`
 
 ## CLI
 
@@ -147,6 +123,7 @@ openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
 openclaw voicecall continue --call-id <id> --message "Any questions?"
 openclaw voicecall speak --call-id <id> --message "One moment"
 openclaw voicecall end --call-id <id>
+openclaw voicecall status --json
 openclaw voicecall status --call-id <id>
 openclaw voicecall tail
 openclaw voicecall expose --mode funnel
@@ -178,4 +155,9 @@ Actions:
 - Adds replay protection for Twilio and Plivo webhooks (valid duplicate callbacks are ignored safely).
 - Twilio speech turns include a per-turn token so stale/replayed callbacks cannot complete a newer turn.
 - `responseModel` / `responseSystemPrompt` control AI auto-responses.
-- Media streaming requires `ws` and OpenAI Realtime API key.
+- Voice-call auto-responses enforce a spoken JSON contract (`{"spoken":"..."}`) and filter reasoning/meta output before playback.
+- While a Twilio stream is active, playback does not fall back to TwiML `<Say>`; stream-TTS failures fail the playback request.
+- Outbound conversation calls suppress barge-in only while the initial greeting is actively speaking, then re-enable normal interruption.
+- Twilio stream disconnect auto-end uses a short grace window so quick reconnects do not end the call.
+- Realtime provider selection is generic. Configure `streaming.provider` / `realtime.provider` and put provider-owned options under `providers.<id>`.
+- Runtime fallback still accepts the old voice-call keys for now, but migration is a doctor step and the compat shim is scheduled to go away in a future release.

package/api.ts

@@ -0,0 +1,16 @@
+export {
+  definePluginEntry,
+  fetchWithSsrFGuard,
+  type GatewayRequestHandlerOptions,
+  isBlockedHostnameOrIp,
+  isRequestBodyLimitError,
+  type OpenClawPluginApi,
+  readRequestBodyWithLimit,
+  requestBodyErrorToText,
+  type SessionEntry,
+  sleep,
+  TtsAutoSchema,
+  TtsConfigSchema,
+  TtsModeSchema,
+  TtsProviderSchema,
+} from "./runtime-api.js";

package/cli-metadata.ts

@@ -0,0 +1,10 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+
+export default definePluginEntry({
+  id: "voice-call",
+  name: "Voice Call",
+  description: "Voice call channel plugin",
+  register(api) {
+    api.registerCli(() => {}, { commands: ["voicecall"] });
+  },
+});

package/config-api.ts

@@ -0,0 +1,12 @@
+// Narrow barrel for config compatibility helpers consumed outside the plugin.
+// Keep this separate from api.ts so config migration code does not pull in the
+// full runtime-oriented voice-call surface.
+
+export {
+  VOICE_CALL_LEGACY_CONFIG_REMOVAL_VERSION,
+  collectVoiceCallLegacyConfigIssues,
+  formatVoiceCallLegacyConfigWarnings,
+  migrateVoiceCallLegacyConfigInput,
+  normalizeVoiceCallLegacyConfigInput,
+  parseVoiceCallPluginConfig,
+} from "./src/config-compat.js";