@openclaw/voice-call 2026.3.13 → 2026.5.2-beta.1

package/src/providers/twilio/twiml-policy.ts

@@ -1,8 +1,7 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
 import type { WebhookContext } from "../../types.js";
 
-export type TwimlResponseKind = "empty" | "pause" | "queue" | "stored" | "stream";
-
-export type TwimlRequestView = {
+type TwimlRequestView = {
   callStatus: string | null;
   direction: string | null;
   isStatusCallback: boolean;
@@ -10,14 +9,14 @@ export type TwimlRequestView = {
   callIdFromQuery?: string;
 };
 
-export type TwimlPolicyInput = TwimlRequestView & {
+type TwimlPolicyInput = TwimlRequestView & {
   hasStoredTwiml: boolean;
   isNotifyCall: boolean;
   hasActiveStreams: boolean;
   canStream: boolean;
 };
 
-export type TwimlDecision =
+type TwimlDecision =
   | {
       kind: "empty" | "pause" | "queue";
       consumeStoredTwimlCallId?: string;
@@ -40,11 +39,8 @@ function isOutboundDirection(direction: string | null): boolean {
 
 export function readTwimlRequestView(ctx: WebhookContext): TwimlRequestView {
   const params = new URLSearchParams(ctx.rawBody);
-  const type = typeof ctx.query?.type === "string" ? ctx.query.type.trim() : undefined;
-  const callIdFromQuery =
-    typeof ctx.query?.callId === "string" && ctx.query.callId.trim()
-      ? ctx.query.callId.trim()
-      : undefined;
+  const type = normalizeOptionalString(ctx.query?.type);
+  const callIdFromQuery = normalizeOptionalString(ctx.query?.callId);
 
   return {
     callStatus: params.get("CallStatus"),

package/src/providers/twilio/webhook.ts

@@ -1,6 +1,6 @@
 import type { WebhookContext, WebhookVerificationResult } from "../../types.js";
 import { verifyTwilioWebhook } from "../../webhook-security.js";
-import type { TwilioProviderOptions } from "../twilio.js";
+import type { TwilioProviderOptions } from "../twilio.types.js";
 
 export function verifyTwilioProviderWebhook(params: {
   ctx: WebhookContext;

package/src/providers/twilio.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { WebhookContext } from "../types.js";
 import { TwilioProvider } from "./twilio.js";
+import { TwilioApiError } from "./twilio/api.js";
 
 const STREAM_URL = "wss://example.ngrok.app/voice/stream";
 
@@ -27,7 +28,123 @@ function expectStreamingTwiml(body: string) {
   expect(body).toContain("<Connect>");
 }
 
+function expectQueueTwiml(body: string) {
+  expect(body).toContain("Please hold while we connect you.");
+  expect(body).toContain("<Enqueue");
+  expect(body).toContain("hold-queue");
+}
+
+function requireResponseBody(body: string | undefined): string {
+  if (!body) {
+    throw new Error("Twilio provider did not return a response body");
+  }
+  return body;
+}
+
+function requireEvent<T>(event: T | undefined, message: string): T {
+  if (!event) {
+    throw new Error(message);
+  }
+  return event;
+}
+
+type TwilioApiRequest = (
+  endpoint: string,
+  params: Record<string, string | string[]>,
+  options?: { allowNotFound?: boolean },
+) => Promise<unknown>;
+
+function createApiRequestMock(impl?: TwilioApiRequest) {
+  return vi.fn<TwilioApiRequest>(impl ?? (async () => ({})));
+}
+
+function createTwilioCallStateRaceError(): TwilioApiError {
+  return new TwilioApiError(
+    400,
+    JSON.stringify({
+      code: 21220,
+      message: "Call is not in-progress. Cannot redirect.",
+    }),
+  );
+}
+
+function configureTelephonyTwiMlFallback(params: { providerCallId: string; streamSid?: string }) {
+  const provider = createProvider();
+  const apiRequest = createApiRequestMock();
+  (
+    provider as unknown as {
+      apiRequest: TwilioApiRequest;
+    }
+  ).apiRequest = apiRequest;
+  (
+    provider as unknown as {
+      callWebhookUrls: Map<string, string>;
+    }
+  ).callWebhookUrls.set(params.providerCallId, "https://example.ngrok.app/voice/twilio");
+  if (params.streamSid) {
+    provider.registerCallStream(params.providerCallId, params.streamSid);
+  }
+  return { provider, apiRequest };
+}
+
 describe("TwilioProvider", () => {
+  it("sends direct initial TwiML for notify-mode outbound calls", async () => {
+    const provider = createProvider();
+    const apiRequest = createApiRequestMock(async () => ({ sid: "CA123", status: "queued" }));
+    (
+      provider as unknown as {
+        apiRequest: TwilioApiRequest;
+      }
+    ).apiRequest = apiRequest;
+
+    const result = await provider.initiateCall({
+      callId: "call-1",
+      from: "+14155550100",
+      to: "+14155550123",
+      webhookUrl: "https://example.ngrok.app/voice/webhook",
+      inlineTwiml: "<Response><Say>Hello</Say></Response>",
+    });
+
+    expect(result).toEqual({ providerCallId: "CA123", status: "queued" });
+    expect(apiRequest).toHaveBeenCalledWith(
+      "/Calls.json",
+      expect.objectContaining({
+        To: "+14155550123",
+        From: "+14155550100",
+        Twiml: "<Response><Say>Hello</Say></Response>",
+        StatusCallback: "https://example.ngrok.app/voice/webhook?callId=call-1&type=status",
+        StatusCallbackEvent: ["initiated", "ringing", "answered", "completed"],
+      }),
+    );
+    expect(apiRequest.mock.calls[0]?.[1]).not.toHaveProperty("Url");
+  });
+
+  it("uses the webhook URL for conversation outbound calls", async () => {
+    const provider = createProvider();
+    const apiRequest = createApiRequestMock(async () => ({ sid: "CA123", status: "queued" }));
+    (
+      provider as unknown as {
+        apiRequest: TwilioApiRequest;
+      }
+    ).apiRequest = apiRequest;
+
+    await provider.initiateCall({
+      callId: "call-1",
+      from: "+14155550100",
+      to: "+14155550123",
+      webhookUrl: "https://example.ngrok.app/voice/webhook",
+    });
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "/Calls.json",
+      expect.objectContaining({
+        Url: "https://example.ngrok.app/voice/webhook?callId=call-1",
+        StatusCallback: "https://example.ngrok.app/voice/webhook?callId=call-1&type=status",
+      }),
+    );
+    expect(apiRequest.mock.calls[0]?.[1]).not.toHaveProperty("Twiml");
+  });
+
   it("returns streaming TwiML for outbound conversation calls before in-progress", () => {
     const provider = createProvider();
     const ctx = createContext("CallStatus=initiated&Direction=outbound-api&CallSid=CA123", {
@@ -36,8 +153,42 @@ describe("TwilioProvider", () => {
 
     const result = provider.parseWebhookEvent(ctx);
 
-    expect(result.providerResponseBody).toBeDefined();
-    expectStreamingTwiml(result.providerResponseBody ?? "");
+    expectStreamingTwiml(requireResponseBody(result.providerResponseBody));
+  });
+
+  it("serves pre-connect TwiML once before outbound streaming starts", async () => {
+    const provider = createProvider();
+    (
+      provider as unknown as {
+        apiRequest: TwilioApiRequest;
+      }
+    ).apiRequest = vi.fn<TwilioApiRequest>(async () => ({
+      sid: "CA999",
+      status: "queued",
+    }));
+    const preConnectTwiml = '<Response><Play digits="ww123456#" /></Response>';
+
+    await provider.initiateCall({
+      callId: "call-1",
+      from: "+15550000001",
+      to: "+15550000002",
+      webhookUrl: "https://example.ngrok.app/voice/twilio",
+      preConnectTwiml,
+    });
+
+    const first = provider.parseWebhookEvent(
+      createContext("CallStatus=initiated&Direction=outbound-api&CallSid=CA999", {
+        callId: "call-1",
+      }),
+    );
+    expect(requireResponseBody(first.providerResponseBody)).toBe(preConnectTwiml);
+
+    const second = provider.parseWebhookEvent(
+      createContext("CallStatus=initiated&Direction=outbound-api&CallSid=CA999", {
+        callId: "call-1",
+      }),
+    );
+    expectStreamingTwiml(requireResponseBody(second.providerResponseBody));
   });
 
   it("returns empty TwiML for status callbacks", () => {
@@ -60,8 +211,7 @@ describe("TwilioProvider", () => {
 
     const result = provider.parseWebhookEvent(ctx);
 
-    expect(result.providerResponseBody).toBeDefined();
-    expectStreamingTwiml(result.providerResponseBody ?? "");
+    expectStreamingTwiml(requireResponseBody(result.providerResponseBody));
   });
 
   it("returns queue TwiML for second inbound call when first call is active", () => {
@@ -72,10 +222,8 @@ describe("TwilioProvider", () => {
     const firstResult = provider.parseWebhookEvent(firstInbound);
     const secondResult = provider.parseWebhookEvent(secondInbound);
 
-    expect(firstResult.providerResponseBody).toContain("<Connect>");
-    expect(secondResult.providerResponseBody).toContain("Please hold while we connect you.");
-    expect(secondResult.providerResponseBody).toContain("<Enqueue");
-    expect(secondResult.providerResponseBody).toContain("hold-queue");
+    expectStreamingTwiml(requireResponseBody(firstResult.providerResponseBody));
+    expectQueueTwiml(requireResponseBody(secondResult.providerResponseBody));
   });
 
   it("connects next inbound call after unregisterCallStream cleanup", () => {
@@ -87,8 +235,9 @@ describe("TwilioProvider", () => {
     provider.unregisterCallStream("CA311");
     const secondResult = provider.parseWebhookEvent(secondInbound);
 
-    expect(secondResult.providerResponseBody).toContain("<Connect>");
-    expect(secondResult.providerResponseBody).not.toContain("hold-queue");
+    const secondBody = requireResponseBody(secondResult.providerResponseBody);
+    expectStreamingTwiml(secondBody);
+    expect(secondBody).not.toContain("hold-queue");
   });
 
   it("cleans up active inbound call on completed status callback", () => {
@@ -103,8 +252,9 @@ describe("TwilioProvider", () => {
     provider.parseWebhookEvent(completed);
     const nextResult = provider.parseWebhookEvent(nextInbound);
 
-    expect(nextResult.providerResponseBody).toContain("<Connect>");
-    expect(nextResult.providerResponseBody).not.toContain("hold-queue");
+    const nextBody = requireResponseBody(nextResult.providerResponseBody);
+    expectStreamingTwiml(nextBody);
+    expect(nextBody).not.toContain("hold-queue");
   });
 
   it("cleans up active inbound call on canceled status callback", () => {
@@ -119,8 +269,9 @@ describe("TwilioProvider", () => {
     provider.parseWebhookEvent(canceled);
     const nextResult = provider.parseWebhookEvent(nextInbound);
 
-    expect(nextResult.providerResponseBody).toContain("<Connect>");
-    expect(nextResult.providerResponseBody).not.toContain("hold-queue");
+    const nextBody = requireResponseBody(nextResult.providerResponseBody);
+    expectStreamingTwiml(nextBody);
+    expect(nextBody).not.toContain("hold-queue");
   });
 
   it("QUEUE_TWIML references /voice/hold-music waitUrl", () => {
@@ -131,7 +282,9 @@ describe("TwilioProvider", () => {
     provider.parseWebhookEvent(firstInbound);
     const result = provider.parseWebhookEvent(secondInbound);
 
-    expect(result.providerResponseBody).toContain('waitUrl="/voice/hold-music"');
+    expect(requireResponseBody(result.providerResponseBody)).toContain(
+      'waitUrl="/voice/hold-music"',
+    );
   });
 
   it("uses a stable fallback dedupeKey for identical request payloads", () => {
@@ -149,11 +302,11 @@ describe("TwilioProvider", () => {
     const eventA = provider.parseWebhookEvent(ctxA).events[0];
     const eventB = provider.parseWebhookEvent(ctxB).events[0];
 
-    expect(eventA).toBeDefined();
-    expect(eventB).toBeDefined();
-    expect(eventA?.id).not.toBe(eventB?.id);
-    expect(eventA?.dedupeKey).toContain("twilio:fallback:");
-    expect(eventA?.dedupeKey).toBe(eventB?.dedupeKey);
+    const first = requireEvent(eventA, "expected first fallback Twilio event");
+    const second = requireEvent(eventB, "expected second fallback Twilio event");
+    expect(first.id).not.toBe(second.id);
+    expect(first.dedupeKey).toContain("twilio:fallback:");
+    expect(first.dedupeKey).toBe(second.dedupeKey);
   });
 
   it("uses verified request key for dedupe and ignores idempotency header changes", () => {
@@ -173,8 +326,12 @@ describe("TwilioProvider", () => {
     const eventB = provider.parseWebhookEvent(ctxB, { verifiedRequestKey: "twilio:req:abc" })
       .events[0];
 
-    expect(eventA?.dedupeKey).toBe("twilio:req:abc");
-    expect(eventB?.dedupeKey).toBe("twilio:req:abc");
+    expect(requireEvent(eventA, "expected verified first Twilio event").dedupeKey).toBe(
+      "twilio:req:abc",
+    );
+    expect(requireEvent(eventB, "expected verified second Twilio event").dedupeKey).toBe(
+      "twilio:req:abc",
+    );
   });
 
   it("keeps turnToken from query on speech events", () => {
@@ -185,7 +342,250 @@ describe("TwilioProvider", () => {
     });
 
     const event = provider.parseWebhookEvent(ctx).events[0];
-    expect(event?.type).toBe("call.speech");
-    expect(event?.turnToken).toBe("turn-xyz");
+    const parsed = requireEvent(event, "expected speech event from Twilio webhook");
+    expect(parsed.type).toBe("call.speech");
+    expect(parsed.turnToken).toBe("turn-xyz");
+  });
+
+  it("fails when an active stream exists but telephony TTS is unavailable", async () => {
+    const { provider, apiRequest } = configureTelephonyTwiMlFallback({
+      providerCallId: "CA-stream",
+      streamSid: "MZ-stream",
+    });
+
+    await expect(
+      provider.playTts({
+        callId: "call-stream",
+        providerCallId: "CA-stream",
+        text: "Hello stream",
+      }),
+    ).rejects.toThrow("refusing TwiML fallback");
+    expect(apiRequest).not.toHaveBeenCalled();
+  });
+
+  it("falls back to TwiML when no active stream exists and telephony TTS is unavailable", async () => {
+    const { provider, apiRequest } = configureTelephonyTwiMlFallback({
+      providerCallId: "CA-nostream",
+    });
+
+    await expect(
+      provider.playTts({
+        callId: "call-nostream",
+        providerCallId: "CA-nostream",
+        text: "Hello TwiML",
+      }),
+    ).resolves.toBeUndefined();
+    expect(apiRequest).toHaveBeenCalledTimes(1);
+    const call = apiRequest.mock.calls[0];
+    const endpoint = call[0];
+    const params = call[1] as { Twiml?: string };
+    expect(endpoint).toBe("/Calls/CA-nostream.json");
+    expect(params.Twiml).toContain("<Say");
+  });
+
+  it("retries TwiML fallback when Twilio briefly rejects a live-call update as not in progress", async () => {
+    vi.useFakeTimers();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const { provider, apiRequest } = configureTelephonyTwiMlFallback({
+        providerCallId: "CA-race-play",
+      });
+      apiRequest.mockRejectedValueOnce(createTwilioCallStateRaceError()).mockResolvedValueOnce({});
+
+      const playback = provider.playTts({
+        callId: "call-race-play",
+        providerCallId: "CA-race-play",
+        text: "Hello after race",
+      });
+      await Promise.resolve();
+      expect(apiRequest).toHaveBeenCalledTimes(1);
+
+      await vi.advanceTimersByTimeAsync(250);
+      await expect(playback).resolves.toBeUndefined();
+
+      expect(apiRequest).toHaveBeenCalledTimes(2);
+      expect(apiRequest.mock.calls[0]?.[0]).toBe("/Calls/CA-race-play.json");
+      expect(apiRequest.mock.calls[1]?.[0]).toBe("/Calls/CA-race-play.json");
+      expect(warn).toHaveBeenCalledWith(
+        "[voice-call] Twilio playTts update hit call state race (21220); retrying in 250ms",
+      );
+    } finally {
+      warn.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("sends DTMF by updating the call and redirecting back to the webhook", async () => {
+    const { provider, apiRequest } = configureTelephonyTwiMlFallback({
+      providerCallId: "CA-dtmf",
+    });
+
+    await expect(
+      provider.sendDtmf({
+        callId: "call-dtmf",
+        providerCallId: "CA-dtmf",
+        digits: "ww123#",
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(apiRequest).toHaveBeenCalledTimes(1);
+    const call = apiRequest.mock.calls[0];
+    const endpoint = call[0];
+    const params = call[1] as { Twiml?: string };
+    expect(endpoint).toBe("/Calls/CA-dtmf.json");
+    expect(params.Twiml).toContain('<Play digits="ww123#"');
+    expect(params.Twiml).toContain("<Redirect");
+    expect(params.Twiml).toContain("https://example.ngrok.app/voice/twilio");
+  });
+
+  it("retries startListening when Twilio briefly rejects a live-call update as not in progress", async () => {
+    vi.useFakeTimers();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const { provider, apiRequest } = configureTelephonyTwiMlFallback({
+        providerCallId: "CA-race-listen",
+      });
+      apiRequest.mockRejectedValueOnce(createTwilioCallStateRaceError()).mockResolvedValueOnce({});
+
+      const listening = provider.startListening({
+        callId: "call-race-listen",
+        providerCallId: "CA-race-listen",
+      });
+      await Promise.resolve();
+      expect(apiRequest).toHaveBeenCalledTimes(1);
+
+      await vi.advanceTimersByTimeAsync(250);
+      await expect(listening).resolves.toBeUndefined();
+
+      expect(apiRequest).toHaveBeenCalledTimes(2);
+      expect(apiRequest.mock.calls[0]?.[0]).toBe("/Calls/CA-race-listen.json");
+      expect(apiRequest.mock.calls[1]?.[0]).toBe("/Calls/CA-race-listen.json");
+      expect(warn).toHaveBeenCalledWith(
+        "[voice-call] Twilio startListening update hit call state race (21220); retrying in 250ms",
+      );
+    } finally {
+      warn.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores stale stream unregister requests that do not match current stream SID", () => {
+    const provider = createProvider();
+    provider.registerCallStream("CA-reconnect", "MZ-new");
+
+    provider.unregisterCallStream("CA-reconnect", "MZ-old");
+    expect(provider.hasRegisteredStream("CA-reconnect")).toBe(true);
+
+    provider.unregisterCallStream("CA-reconnect", "MZ-new");
+    expect(provider.hasRegisteredStream("CA-reconnect")).toBe(false);
+  });
+
+  it("times out telephony synthesis in stream mode and does not send completion mark", async () => {
+    vi.useFakeTimers();
+    try {
+      const provider = createProvider();
+      provider.registerCallStream("CA-timeout", "MZ-timeout");
+
+      const sendAudio = vi.fn();
+      const sendMark = vi.fn();
+      const mediaStreamHandler = {
+        queueTts: async (
+          _streamSid: string,
+          playFn: (signal: AbortSignal) => Promise<void>,
+        ): Promise<void> => {
+          await playFn(new AbortController().signal);
+        },
+        sendAudio,
+        sendMark,
+      };
+
+      provider.setMediaStreamHandler(mediaStreamHandler as never);
+      provider.setTTSProvider({
+        synthesisTimeoutMs: 5000,
+        synthesizeForTelephony: async () => await new Promise<Buffer>(() => {}),
+      });
+
+      const playExpectation = expect(
+        provider.playTts({
+          callId: "call-timeout",
+          providerCallId: "CA-timeout",
+          text: "Timeout me",
+        }),
+      ).rejects.toThrow("Telephony TTS synthesis timed out after 5000ms");
+      await vi.advanceTimersByTimeAsync(5_100);
+      await playExpectation;
+      expect(sendAudio).toHaveBeenCalled();
+      expect(sendMark).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("fails stream playback when all audio sends and completion mark are dropped", async () => {
+    const provider = createProvider();
+    provider.registerCallStream("CA-dropped", "MZ-dropped");
+
+    const sendAudio = vi.fn(() => ({ sent: false }));
+    const sendMark = vi.fn(() => ({ sent: false }));
+    const mediaStreamHandler = {
+      queueTts: async (
+        _streamSid: string,
+        playFn: (signal: AbortSignal) => Promise<void>,
+      ): Promise<void> => {
+        await playFn(new AbortController().signal);
+      },
+      sendAudio,
+      sendMark,
+    };
+
+    provider.setMediaStreamHandler(mediaStreamHandler as never);
+    provider.setTTSProvider({
+      synthesisTimeoutMs: 5000,
+      synthesizeForTelephony: async () => Buffer.alloc(320),
+    });
+
+    await expect(
+      provider.playTts({
+        callId: "call-dropped",
+        providerCallId: "CA-dropped",
+        text: "Dropped audio",
+      }),
+    ).rejects.toThrow("Telephony stream playback failed");
+    expect(sendAudio).toHaveBeenCalled();
+    expect(sendMark).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails stream playback when telephony synthesis returns empty audio", async () => {
+    const provider = createProvider();
+    provider.registerCallStream("CA-empty", "MZ-empty");
+
+    const sendAudio = vi.fn();
+    const sendMark = vi.fn();
+    const mediaStreamHandler = {
+      queueTts: async (
+        _streamSid: string,
+        playFn: (signal: AbortSignal) => Promise<void>,
+      ): Promise<void> => {
+        await playFn(new AbortController().signal);
+      },
+      sendAudio,
+      sendMark,
+    };
+
+    provider.setMediaStreamHandler(mediaStreamHandler as never);
+    provider.setTTSProvider({
+      synthesisTimeoutMs: 5000,
+      synthesizeForTelephony: async () => Buffer.alloc(0),
+    });
+
+    await expect(
+      provider.playTts({
+        callId: "call-empty",
+        providerCallId: "CA-empty",
+        text: "Empty audio",
+      }),
+    ).rejects.toThrow("Telephony TTS produced no audio");
+    expect(sendAudio).toHaveBeenCalled();
+    expect(sendMark).not.toHaveBeenCalled();
   });
 });