Voice call configuration

Plugin config keys, the call owner, the full config reference table, and session scope. Part of the Voice call plugin guide.

Configuration

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 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 | main
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, how can I help?",
              responseSystemPrompt: "You are a concise baseball card specialist.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optional: us1 | ie1 | au1; defaults to us1
          },
          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", port: 8443, path: "/voice/webhook" },

          outbound: {
            defaultMode: "notify", // notify | conversation
          },

          streaming: { enabled: true /* Twilio only; see Streaming transcription */ },
          realtime: { enabled: false /* see Realtime voice conversations */ },
        },
      },
    },
  },
}

Choose the call owner

With one configured agent, Voice Call uses that agent automatically. With multiple agents, set plugins.entries.voice-call.config.agentId to the intended response and session owner. main is an ordinary agent ID, not a fallback for a multi-agent fleet. Per-number routes may choose different agents for inbound calls, but do not replace the plugin's startup owner.

If startup reports that Voice Call has no explicit owner, list your agents with openclaw agents list, set the existing agentId field, and rerun openclaw voicecall setup. With the default hybrid reload mode, the configuration change reloads the plugin automatically; see Hot reload. Existing legacy default-agent selection is preserved; new multi-agent setups should use an explicit owner. See Agent configuration.

Config reference

Top-level keys under plugins.entries.voice-call.config not shown above:

Twilio defaults to its US1 REST endpoint. To process calls in a supported non-US Region, set twilio.region to ie1 or au1 and use credentials from that Region. See Twilio's non-US REST API guide.

Twilio voicemail detection tuning

Set voicemail.detection: "twilio" to enable answering-machine detection. These optional voicemail keys tune Twilio's detection on outbound calls:

The speech threshold defaults to Twilio's maximum of six seconds to reduce false machine results for talkative humans and longer business greetings. Twilio's own default is 2400 ms. A higher threshold also delays machine detection; it cannot reliably classify a human who speaks without pausing for thirty seconds. Tune it across representative greetings and carriers.

The other defaults match Twilio. All values are integers in milliseconds; the plugin converts machineDetectionTimeoutMs to whole seconds for the Calls API's MachineDetectionTimeout. The three other values pass through in milliseconds. The allowed ranges follow Twilio's AMD tuning reference and its invalid detection configuration error.

Session scope

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.

Set sessionScope: "main" to route every call into the configured agent's main session, agent:<agentId>:main, or global when core session.scope is "global". Custom core session.mainKey values are ignored. Raw call turns then share history with the agent's primary session, so use this only when that shared context is intentional.

For per-phone and per-call, Voice Call stores generated session keys under the configured agent namespace (agent:<agentId>:voice:*). Raw explicit integration keys resolve into the same namespace: a canonical agent:<configuredAgentId>:* key keeps that owner and honors core main-session/global-scope aliasing; foreign or malformed agent:* input is scoped as an opaque key under the configured agent; global and unknown remain global sentinels.