@bot/voice-call

Official Voice Call plugin for Hanzo Bot.

Providers:

Twilio (Programmable Voice + Media Streams)
Telnyx (Call Control v2)
Plivo (Voice API + XML transfer + GetInput speech)
Mock (dev/no network)

Docs: https://docs.hanzo.bot/plugins/voice-call Plugin system: https://docs.hanzo.bot/plugin

Install (local dev)

Option A: install via Hanzo Bot (recommended)

hanzo-bot plugins install @bot/voice-call

Restart the Gateway afterwards.

Option B: copy into your global extensions folder (dev)

mkdir -p ~/.hanzo/bot/extensions
cp -R extensions/voice-call ~/.hanzo/bot/extensions/voice-call
cd ~/.hanzo/bot/extensions/voice-call && pnpm install

Config

Put under plugins.entries.voice-call.config:

{
  provider: "twilio", // or "telnyx" | "plivo" | "mock"
  fromNumber: "+15550001234",
  toNumber: "+15550005678",

  twilio: {
    accountSid: "ACxxxxxxxx",
    authToken: "your_token",
  },

  telnyx: {
    apiKey: "KEYxxxx",
    connectionId: "CONNxxxx",
    // Telnyx webhook public key from the Telnyx Mission Control Portal
    // (Base64 string; can also be set via TELNYX_PUBLIC_KEY).
    publicKey: "...",
  },

  plivo: {
    authId: "MAxxxxxxxxxxxxxxxxxxxx",
    authToken: "your_token",
  },

  // Webhook server
  serve: {
    port: 3334,
    path: "/voice/webhook",
  },

  // Public exposure (pick one):
  // publicUrl: "https://example.ngrok.app/voice/webhook",
  // tunnel: { provider: "ngrok" },
  // tailscale: { mode: "funnel", path: "/voice/webhook" }

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

  streaming: {
    enabled: true,
    streamPath: "/voice/stream",
  },
}

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.

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.

{
  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.

CLI

hanzo-bot voicecall call --to "+15555550123" --message "Hello from Hanzo Bot"
hanzo-bot voicecall continue --call-id <id> --message "Any questions?"
hanzo-bot voicecall speak --call-id <id> --message "One moment"
hanzo-bot voicecall end --call-id <id>
hanzo-bot voicecall status --call-id <id>
hanzo-bot voicecall tail
hanzo-bot voicecall expose --mode funnel

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)

Gateway RPC

voicecall.initiate (to?, message, mode?)
voicecall.continue (callId, message)
voicecall.speak (callId, message)
voicecall.end (callId)
voicecall.status (callId)

Notes

Uses webhook signature verification for Twilio/Telnyx/Plivo.
responseModel / responseSystemPrompt control AI auto-responses.
Media streaming requires ws and OpenAI Realtime API key.