@clawdbot/voice-call 0.1.0 → 2026.1.16

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026.1.16
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
+## 2026.1.15
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
+## 2026.1.14
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 0.1.0
 
 ### Highlights

package/README.md

@@ -5,6 +5,7 @@ Official Voice Call plugin for **Clawdbot**.
 Providers:
 - **Twilio** (Programmable Voice + Media Streams)
 - **Telnyx** (Call Control v2)
+- **Plivo** (Voice API + XML transfer + GetInput speech)
 - **Mock** (dev/no network)
 
 Docs: `https://docs.clawd.bot/plugins/voice-call`
@@ -34,7 +35,7 @@ Put under `plugins.entries.voice-call.config`:
 
 ```json5
 {
-  provider: "twilio", // or "telnyx" | "mock"
+  provider: "twilio", // or "telnyx" | "plivo" | "mock"
   fromNumber: "+15550001234",
   toNumber: "+15550005678",
 
@@ -43,6 +44,11 @@ Put under `plugins.entries.voice-call.config`:
     authToken: "your_token"
   },
 
+  plivo: {
+    authId: "MAxxxxxxxxxxxxxxxxxxxx",
+    authToken: "your_token"
+  },
+
   // Webhook server
   serve: {
     port: 3334,
@@ -66,7 +72,7 @@ Put under `plugins.entries.voice-call.config`:
 ```
 
 Notes:
-- Twilio/Telnyx require a **publicly reachable** webhook URL.
+- Twilio/Telnyx/Plivo require a **publicly reachable** webhook URL.
 - `mock` is a local dev provider (no network calls).
 
 ## CLI
@@ -102,6 +108,6 @@ Actions:
 
 ## Notes
 
-- Uses webhook signature verification for Twilio/Telnyx.
+- Uses webhook signature verification for Twilio/Telnyx/Plivo.
 - `responseModel` / `responseSystemPrompt` control AI auto-responses.
 - Media streaming requires `ws` and OpenAI Realtime API key.

package/index.ts

@@ -125,7 +125,7 @@ const VoiceCallToolSchema = Type.Union([
 const voiceCallPlugin = {
   id: "voice-call",
   name: "Voice Call",
-  description: "Voice-call plugin with Telnyx/Twilio providers",
+  description: "Voice-call plugin with Telnyx/Twilio/Plivo providers",
   configSchema: voiceCallConfigSchema,
   register(api) {
     const cfg = voiceCallConfigSchema.parse(api.pluginConfig);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/voice-call",
-  "version": "0.1.0",
+  "version": "2026.1.16",
   "type": "module",
   "description": "Clawdbot voice-call plugin",
   "dependencies": {
@@ -9,6 +9,8 @@
     "zod": "^4.3.5"
   },
   "clawdbot": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   }
 }

package/src/cli.ts

@@ -42,7 +42,10 @@ export function registerVoiceCallCli(params: {
   logger: Logger;
 }) {
   const { program, config, ensureRuntime, logger } = params;
-  const root = program.command("voicecall").description("Voice call utilities");
+  const root = program
+    .command("voicecall")
+    .description("Voice call utilities")
+    .addHelpText("after", () => `\nDocs: https://docs.clawd.bot/cli/voicecall\n`);
 
   root
     .command("call")

package/src/config.ts

@@ -53,6 +53,14 @@ export const TwilioConfigSchema = z.object({
 });
 export type TwilioConfig = z.infer<typeof TwilioConfigSchema>;
 
+export const PlivoConfigSchema = z.object({
+  /** Plivo Auth ID (starts with MA/SA) */
+  authId: z.string().min(1).optional(),
+  /** Plivo Auth Token */
+  authToken: z.string().min(1).optional(),
+});
+export type PlivoConfig = z.infer<typeof PlivoConfigSchema>;
+
 // -----------------------------------------------------------------------------
 // STT/TTS Configuration
 // -----------------------------------------------------------------------------
@@ -219,8 +227,8 @@ export const VoiceCallConfigSchema = z.object({
   /** Enable voice call functionality */
   enabled: z.boolean().default(false),
 
-  /** Active provider (telnyx, twilio, or mock) */
-  provider: z.enum(["telnyx", "twilio", "mock"]).optional(),
+  /** Active provider (telnyx, twilio, plivo, or mock) */
+  provider: z.enum(["telnyx", "twilio", "plivo", "mock"]).optional(),
 
   /** Telnyx-specific configuration */
   telnyx: TelnyxConfigSchema.optional(),
@@ -228,6 +236,9 @@ export const VoiceCallConfigSchema = z.object({
   /** Twilio-specific configuration */
   twilio: TwilioConfigSchema.optional(),
 
+  /** Plivo-specific configuration */
+  plivo: PlivoConfigSchema.optional(),
+
   /** Phone number to call from (E.164) */
   fromNumber: E164Schema.optional(),
 
@@ -351,5 +362,18 @@ export function validateProviderConfig(config: VoiceCallConfig): {
     }
   }
 
+  if (config.provider === "plivo") {
+    if (!config.plivo?.authId) {
+      errors.push(
+        "plugins.entries.voice-call.config.plivo.authId is required (or set PLIVO_AUTH_ID env)",
+      );
+    }
+    if (!config.plivo?.authToken) {
+      errors.push(
+        "plugins.entries.voice-call.config.plivo.authToken is required (or set PLIVO_AUTH_TOKEN env)",
+      );
+    }
+  }
+
   return { valid: errors.length === 0, errors };
 }

package/src/manager/context.ts

@@ -0,0 +1,22 @@
+import type { CallId, CallRecord } from "../types.js";
+import type { VoiceCallConfig } from "../config.js";
+import type { VoiceCallProvider } from "../providers/base.js";
+
+export type TranscriptWaiter = {
+  resolve: (text: string) => void;
+  reject: (err: Error) => void;
+  timeout: NodeJS.Timeout;
+};
+
+export type CallManagerContext = {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  processedEventIds: Set<string>;
+  provider: VoiceCallProvider | null;
+  config: VoiceCallConfig;
+  storePath: string;
+  webhookUrl: string | null;
+  transcriptWaiters: Map<CallId, TranscriptWaiter>;
+  maxDurationTimers: Map<CallId, NodeJS.Timeout>;
+};
+

package/src/manager/events.ts

@@ -0,0 +1,178 @@
+import crypto from "node:crypto";
+
+import type { CallId, CallRecord, CallState, NormalizedEvent } from "../types.js";
+import { TerminalStates } from "../types.js";
+import type { CallManagerContext } from "./context.js";
+import { findCall } from "./lookup.js";
+import { addTranscriptEntry, transitionState } from "./state.js";
+import { persistCallRecord } from "./store.js";
+import {
+  clearMaxDurationTimer,
+  rejectTranscriptWaiter,
+  resolveTranscriptWaiter,
+  startMaxDurationTimer,
+} from "./timers.js";
+import { endCall } from "./outbound.js";
+
+function shouldAcceptInbound(config: CallManagerContext["config"], from: string | undefined): boolean {
+  const { inboundPolicy: policy, allowFrom } = config;
+
+  switch (policy) {
+    case "disabled":
+      console.log("[voice-call] Inbound call rejected: policy is disabled");
+      return false;
+
+    case "open":
+      console.log("[voice-call] Inbound call accepted: policy is open");
+      return true;
+
+    case "allowlist":
+    case "pairing": {
+      const normalized = from?.replace(/\D/g, "") || "";
+      const allowed = (allowFrom || []).some((num) => {
+        const normalizedAllow = num.replace(/\D/g, "");
+        return normalized.endsWith(normalizedAllow) || normalizedAllow.endsWith(normalized);
+      });
+      const status = allowed ? "accepted" : "rejected";
+      console.log(
+        `[voice-call] Inbound call ${status}: ${from} ${allowed ? "is in" : "not in"} allowlist`,
+      );
+      return allowed;
+    }
+
+    default:
+      return false;
+  }
+}
+
+function createInboundCall(params: {
+  ctx: CallManagerContext;
+  providerCallId: string;
+  from: string;
+  to: string;
+}): CallRecord {
+  const callId = crypto.randomUUID();
+
+  const callRecord: CallRecord = {
+    callId,
+    providerCallId: params.providerCallId,
+    provider: params.ctx.provider?.name || "twilio",
+    direction: "inbound",
+    state: "ringing",
+    from: params.from,
+    to: params.to,
+    startedAt: Date.now(),
+    transcript: [],
+    processedEventIds: [],
+    metadata: {
+      initialMessage: params.ctx.config.inboundGreeting || "Hello! How can I help you today?",
+    },
+  };
+
+  params.ctx.activeCalls.set(callId, callRecord);
+  params.ctx.providerCallIdMap.set(params.providerCallId, callId);
+  persistCallRecord(params.ctx.storePath, callRecord);
+
+  console.log(`[voice-call] Created inbound call record: ${callId} from ${params.from}`);
+  return callRecord;
+}
+
+export function processEvent(ctx: CallManagerContext, event: NormalizedEvent): void {
+  if (ctx.processedEventIds.has(event.id)) return;
+  ctx.processedEventIds.add(event.id);
+
+  let call = findCall({
+    activeCalls: ctx.activeCalls,
+    providerCallIdMap: ctx.providerCallIdMap,
+    callIdOrProviderCallId: event.callId,
+  });
+
+  if (!call && event.direction === "inbound" && event.providerCallId) {
+    if (!shouldAcceptInbound(ctx.config, event.from)) {
+      // TODO: Could hang up the call here.
+      return;
+    }
+
+    call = createInboundCall({
+      ctx,
+      providerCallId: event.providerCallId,
+      from: event.from || "unknown",
+      to: event.to || ctx.config.fromNumber || "unknown",
+    });
+
+    // Normalize event to internal ID for downstream consumers.
+    event.callId = call.callId;
+  }
+
+  if (!call) return;
+
+  if (event.providerCallId && !call.providerCallId) {
+    call.providerCallId = event.providerCallId;
+    ctx.providerCallIdMap.set(event.providerCallId, call.callId);
+  }
+
+  call.processedEventIds.push(event.id);
+
+  switch (event.type) {
+    case "call.initiated":
+      transitionState(call, "initiated");
+      break;
+
+    case "call.ringing":
+      transitionState(call, "ringing");
+      break;
+
+    case "call.answered":
+      call.answeredAt = event.timestamp;
+      transitionState(call, "answered");
+      startMaxDurationTimer({
+        ctx,
+        callId: call.callId,
+        onTimeout: async (callId) => {
+          await endCall(ctx, callId);
+        },
+      });
+      break;
+
+    case "call.active":
+      transitionState(call, "active");
+      break;
+
+    case "call.speaking":
+      transitionState(call, "speaking");
+      break;
+
+    case "call.speech":
+      if (event.isFinal) {
+        addTranscriptEntry(call, "user", event.transcript);
+        resolveTranscriptWaiter(ctx, call.callId, event.transcript);
+      }
+      transitionState(call, "listening");
+      break;
+
+    case "call.ended":
+      call.endedAt = event.timestamp;
+      call.endReason = event.reason;
+      transitionState(call, event.reason as CallState);
+      clearMaxDurationTimer(ctx, call.callId);
+      rejectTranscriptWaiter(ctx, call.callId, `Call ended: ${event.reason}`);
+      ctx.activeCalls.delete(call.callId);
+      if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+      break;
+
+    case "call.error":
+      if (!event.retryable) {
+        call.endedAt = event.timestamp;
+        call.endReason = "error";
+        transitionState(call, "error");
+        clearMaxDurationTimer(ctx, call.callId);
+        rejectTranscriptWaiter(ctx, call.callId, `Call error: ${event.error}`);
+        ctx.activeCalls.delete(call.callId);
+        if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+      }
+      break;
+  }
+
+  persistCallRecord(ctx.storePath, call);
+}
+

package/src/manager/lookup.ts

@@ -0,0 +1,34 @@
+import type { CallId, CallRecord } from "../types.js";
+
+export function getCallByProviderCallId(params: {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  providerCallId: string;
+}): CallRecord | undefined {
+  const callId = params.providerCallIdMap.get(params.providerCallId);
+  if (callId) {
+    return params.activeCalls.get(callId);
+  }
+
+  for (const call of params.activeCalls.values()) {
+    if (call.providerCallId === params.providerCallId) {
+      return call;
+    }
+  }
+  return undefined;
+}
+
+export function findCall(params: {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  callIdOrProviderCallId: string;
+}): CallRecord | undefined {
+  const directCall = params.activeCalls.get(params.callIdOrProviderCallId);
+  if (directCall) return directCall;
+  return getCallByProviderCallId({
+    activeCalls: params.activeCalls,
+    providerCallIdMap: params.providerCallIdMap,
+    providerCallId: params.callIdOrProviderCallId,
+  });
+}
+

package/src/manager/outbound.ts

@@ -0,0 +1,247 @@
+import crypto from "node:crypto";
+
+import { TerminalStates, type CallId, type CallRecord, type OutboundCallOptions } from "../types.js";
+import type { CallMode } from "../config.js";
+import { mapVoiceToPolly } from "../voice-mapping.js";
+import type { CallManagerContext } from "./context.js";
+import { getCallByProviderCallId } from "./lookup.js";
+import { generateNotifyTwiml } from "./twiml.js";
+import { addTranscriptEntry, transitionState } from "./state.js";
+import { persistCallRecord } from "./store.js";
+import { clearMaxDurationTimer, clearTranscriptWaiter, rejectTranscriptWaiter, waitForFinalTranscript } from "./timers.js";
+
+export async function initiateCall(
+  ctx: CallManagerContext,
+  to: string,
+  sessionKey?: string,
+  options?: OutboundCallOptions | string,
+): Promise<{ callId: CallId; success: boolean; error?: string }> {
+  const opts: OutboundCallOptions =
+    typeof options === "string" ? { message: options } : (options ?? {});
+  const initialMessage = opts.message;
+  const mode = opts.mode ?? ctx.config.outbound.defaultMode;
+
+  if (!ctx.provider) {
+    return { callId: "", success: false, error: "Provider not initialized" };
+  }
+  if (!ctx.webhookUrl) {
+    return { callId: "", success: false, error: "Webhook URL not configured" };
+  }
+
+  if (ctx.activeCalls.size >= ctx.config.maxConcurrentCalls) {
+    return {
+      callId: "",
+      success: false,
+      error: `Maximum concurrent calls (${ctx.config.maxConcurrentCalls}) reached`,
+    };
+  }
+
+  const callId = crypto.randomUUID();
+  const from =
+    ctx.config.fromNumber ||
+    (ctx.provider?.name === "mock" ? "+15550000000" : undefined);
+  if (!from) {
+    return { callId: "", success: false, error: "fromNumber not configured" };
+  }
+
+  const callRecord: CallRecord = {
+    callId,
+    provider: ctx.provider.name,
+    direction: "outbound",
+    state: "initiated",
+    from,
+    to,
+    sessionKey,
+    startedAt: Date.now(),
+    transcript: [],
+    processedEventIds: [],
+    metadata: {
+      ...(initialMessage && { initialMessage }),
+      mode,
+    },
+  };
+
+  ctx.activeCalls.set(callId, callRecord);
+  persistCallRecord(ctx.storePath, callRecord);
+
+  try {
+    // For notify mode with a message, use inline TwiML with <Say>.
+    let inlineTwiml: string | undefined;
+    if (mode === "notify" && initialMessage) {
+      const pollyVoice = mapVoiceToPolly(ctx.config.tts.voice);
+      inlineTwiml = generateNotifyTwiml(initialMessage, pollyVoice);
+      console.log(`[voice-call] Using inline TwiML for notify mode (voice: ${pollyVoice})`);
+    }
+
+    const result = await ctx.provider.initiateCall({
+      callId,
+      from,
+      to,
+      webhookUrl: ctx.webhookUrl,
+      inlineTwiml,
+    });
+
+    callRecord.providerCallId = result.providerCallId;
+    ctx.providerCallIdMap.set(result.providerCallId, callId);
+    persistCallRecord(ctx.storePath, callRecord);
+
+    return { callId, success: true };
+  } catch (err) {
+    callRecord.state = "failed";
+    callRecord.endedAt = Date.now();
+    callRecord.endReason = "failed";
+    persistCallRecord(ctx.storePath, callRecord);
+    ctx.activeCalls.delete(callId);
+    if (callRecord.providerCallId) {
+      ctx.providerCallIdMap.delete(callRecord.providerCallId);
+    }
+
+    return {
+      callId,
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function speak(
+  ctx: CallManagerContext,
+  callId: CallId,
+  text: string,
+): Promise<{ success: boolean; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: false, error: "Call has ended" };
+
+  try {
+    transitionState(call, "speaking");
+    persistCallRecord(ctx.storePath, call);
+
+    addTranscriptEntry(call, "bot", text);
+
+    await ctx.provider.playTts({
+      callId,
+      providerCallId: call.providerCallId,
+      text,
+      voice: ctx.config.tts.voice,
+    });
+
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function speakInitialMessage(
+  ctx: CallManagerContext,
+  providerCallId: string,
+): Promise<void> {
+  const call = getCallByProviderCallId({
+    activeCalls: ctx.activeCalls,
+    providerCallIdMap: ctx.providerCallIdMap,
+    providerCallId,
+  });
+  if (!call) {
+    console.warn(`[voice-call] speakInitialMessage: no call found for ${providerCallId}`);
+    return;
+  }
+
+  const initialMessage = call.metadata?.initialMessage as string | undefined;
+  const mode = (call.metadata?.mode as CallMode) ?? "conversation";
+
+  if (!initialMessage) {
+    console.log(`[voice-call] speakInitialMessage: no initial message for ${call.callId}`);
+    return;
+  }
+
+  // Clear so we don't speak it again if the provider reconnects.
+  if (call.metadata) {
+    delete call.metadata.initialMessage;
+    persistCallRecord(ctx.storePath, call);
+  }
+
+  console.log(`[voice-call] Speaking initial message for call ${call.callId} (mode: ${mode})`);
+  const result = await speak(ctx, call.callId, initialMessage);
+  if (!result.success) {
+    console.warn(`[voice-call] Failed to speak initial message: ${result.error}`);
+    return;
+  }
+
+  if (mode === "notify") {
+    const delaySec = ctx.config.outbound.notifyHangupDelaySec;
+    console.log(`[voice-call] Notify mode: auto-hangup in ${delaySec}s for call ${call.callId}`);
+    setTimeout(async () => {
+      const currentCall = ctx.activeCalls.get(call.callId);
+      if (currentCall && !TerminalStates.has(currentCall.state)) {
+        console.log(`[voice-call] Notify mode: hanging up call ${call.callId}`);
+        await endCall(ctx, call.callId);
+      }
+    }, delaySec * 1000);
+  }
+}
+
+export async function continueCall(
+  ctx: CallManagerContext,
+  callId: CallId,
+  prompt: string,
+): Promise<{ success: boolean; transcript?: string; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: false, error: "Call has ended" };
+
+  try {
+    await speak(ctx, callId, prompt);
+
+    transitionState(call, "listening");
+    persistCallRecord(ctx.storePath, call);
+
+    await ctx.provider.startListening({ callId, providerCallId: call.providerCallId });
+
+    const transcript = await waitForFinalTranscript(ctx, callId);
+
+    // Best-effort: stop listening after final transcript.
+    await ctx.provider.stopListening({ callId, providerCallId: call.providerCallId });
+
+    return { success: true, transcript };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    clearTranscriptWaiter(ctx, callId);
+  }
+}
+
+export async function endCall(
+  ctx: CallManagerContext,
+  callId: CallId,
+): Promise<{ success: boolean; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: true };
+
+  try {
+    await ctx.provider.hangupCall({
+      callId,
+      providerCallId: call.providerCallId,
+      reason: "hangup-bot",
+    });
+
+    call.state = "hangup-bot";
+    call.endedAt = Date.now();
+    call.endReason = "hangup-bot";
+    persistCallRecord(ctx.storePath, call);
+
+    clearMaxDurationTimer(ctx, callId);
+    rejectTranscriptWaiter(ctx, callId, "Call ended: hangup-bot");
+
+    ctx.activeCalls.delete(callId);
+    if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+

package/src/manager/state.ts

@@ -0,0 +1,51 @@
+import { TerminalStates, type CallRecord, type CallState, type TranscriptEntry } from "../types.js";
+
+const ConversationStates = new Set<CallState>(["speaking", "listening"]);
+
+const StateOrder: readonly CallState[] = [
+  "initiated",
+  "ringing",
+  "answered",
+  "active",
+  "speaking",
+  "listening",
+];
+
+export function transitionState(call: CallRecord, newState: CallState): void {
+  // No-op for same state or already terminal.
+  if (call.state === newState || TerminalStates.has(call.state)) return;
+
+  // Terminal states can always be reached from non-terminal.
+  if (TerminalStates.has(newState)) {
+    call.state = newState;
+    return;
+  }
+
+  // Allow cycling between speaking and listening (multi-turn conversations).
+  if (ConversationStates.has(call.state) && ConversationStates.has(newState)) {
+    call.state = newState;
+    return;
+  }
+
+  // Only allow forward transitions in state order.
+  const currentIndex = StateOrder.indexOf(call.state);
+  const newIndex = StateOrder.indexOf(newState);
+  if (newIndex > currentIndex) {
+    call.state = newState;
+  }
+}
+
+export function addTranscriptEntry(
+  call: CallRecord,
+  speaker: "bot" | "user",
+  text: string,
+): void {
+  const entry: TranscriptEntry = {
+    timestamp: Date.now(),
+    speaker,
+    text,
+    isFinal: true,
+  };
+  call.transcript.push(entry);
+}
+