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

package/src/providers/shared/call-status.ts

@@ -1,3 +1,4 @@
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
 import type { EndReason } from "../../types.js";
 
 const TERMINAL_PROVIDER_STATUS_TO_END_REASON: Record<string, EndReason> = {
@@ -9,7 +10,7 @@ const TERMINAL_PROVIDER_STATUS_TO_END_REASON: Record<string, EndReason> = {
 };
 
 export function normalizeProviderStatus(status: string | null | undefined): string {
-  const normalized = status?.trim().toLowerCase();
+  const normalized = normalizeOptionalLowercaseString(status);
   return normalized && normalized.length > 0 ? normalized : "unknown";
 }
 

package/src/providers/shared/guarded-json-api.test.ts

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { fetchWithSsrFGuardMock } = vi.hoisted(() => ({
+  fetchWithSsrFGuardMock: vi.fn(),
+}));
+
+vi.mock("../../../api.js", () => ({
+  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
+}));
+
+import { guardedJsonApiRequest } from "./guarded-json-api.js";
+
+describe("guardedJsonApiRequest", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses the SSRF-guarded fetch and parses json responses", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(JSON.stringify({ ok: true }), { status: 200 }),
+      release,
+    });
+
+    await expect(
+      guardedJsonApiRequest({
+        url: "https://api.example.com/v1/calls",
+        method: "POST",
+        headers: { Authorization: "Bearer token" },
+        body: { hello: "world" },
+        allowedHostnames: ["api.example.com"],
+        auditContext: "voice-call:test",
+        errorPrefix: "request failed",
+      }),
+    ).resolves.toEqual({ ok: true });
+
+    expect(fetchWithSsrFGuardMock).toHaveBeenCalledWith({
+      url: "https://api.example.com/v1/calls",
+      init: {
+        method: "POST",
+        headers: { Authorization: "Bearer token" },
+        body: JSON.stringify({ hello: "world" }),
+      },
+      policy: { allowedHostnames: ["api.example.com"] },
+      auditContext: "voice-call:test",
+    });
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns undefined for empty bodies and allowed 404s", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValueOnce({
+      response: new Response(null, { status: 204 }),
+      release,
+    });
+
+    await expect(
+      guardedJsonApiRequest({
+        url: "https://api.example.com/v1/calls/1",
+        method: "GET",
+        headers: {},
+        allowedHostnames: ["api.example.com"],
+        auditContext: "voice-call:test",
+        errorPrefix: "request failed",
+      }),
+    ).resolves.toBeUndefined();
+
+    fetchWithSsrFGuardMock.mockResolvedValueOnce({
+      response: new Response("missing", { status: 404 }),
+      release,
+    });
+
+    await expect(
+      guardedJsonApiRequest({
+        url: "https://api.example.com/v1/calls/2",
+        method: "GET",
+        headers: {},
+        allowNotFound: true,
+        allowedHostnames: ["api.example.com"],
+        auditContext: "voice-call:test",
+        errorPrefix: "request failed",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("throws prefixed errors and still releases the response handle", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response("boom", { status: 500 }),
+      release,
+    });
+
+    await expect(
+      guardedJsonApiRequest({
+        url: "https://api.example.com/v1/calls/3",
+        method: "DELETE",
+        headers: {},
+        allowedHostnames: ["api.example.com"],
+        auditContext: "voice-call:test",
+        errorPrefix: "provider error",
+      }),
+    ).rejects.toThrow("provider error: 500 boom");
+
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+});

package/src/providers/shared/guarded-json-api.ts

@@ -1,4 +1,4 @@
-import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/voice-call";
+import { fetchWithSsrFGuard } from "../../../api.js";
 
 type GuardedJsonApiRequestParams = {
   url: string;

package/src/providers/telnyx.test.ts

@@ -1,8 +1,20 @@
 import crypto from "node:crypto";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { WebhookContext } from "../types.js";
 import { TelnyxProvider } from "./telnyx.js";
 
+const apiMocks = vi.hoisted(() => ({
+  fetchWithSsrFGuard: vi.fn(),
+}));
+
+vi.mock("../../api.js", () => ({
+  fetchWithSsrFGuard: apiMocks.fetchWithSsrFGuard,
+}));
+
+afterEach(() => {
+  apiMocks.fetchWithSsrFGuard.mockReset();
+});
+
 function createCtx(params?: Partial<WebhookContext>): WebhookContext {
   return {
     headers: {},
@@ -46,8 +58,25 @@ function expectReplayVerification(
 ) {
   expect(results.map((result) => result.ok)).toEqual([true, true]);
   expect(results.map((result) => Boolean(result.isReplay))).toEqual([false, true]);
-  expect(results[0]?.verifiedRequestKey).toEqual(expect.any(String));
-  expect(results[1]?.verifiedRequestKey).toBe(results[0]?.verifiedRequestKey);
+  const firstResult = results[0];
+  if (!firstResult?.verifiedRequestKey) {
+    throw new Error("expected Telnyx verification to produce a request key");
+  }
+  const secondResult = results[1];
+  if (!secondResult?.verifiedRequestKey) {
+    throw new Error("expected replayed Telnyx verification to preserve the request key");
+  }
+  const firstKey = firstResult.verifiedRequestKey;
+  const secondKey = secondResult.verifiedRequestKey;
+  expect(firstKey.length).toBeGreaterThan(0);
+  expect(secondKey).toBe(firstKey);
+}
+
+function requireJwkX(jwk: JsonWebKey) {
+  if (typeof jwk.x !== "string" || jwk.x.length === 0) {
+    throw new Error("expected Ed25519 JWK export to expose x");
+  }
+  return jwk.x;
 }
 
 function expectWebhookVerificationSucceeds(params: {
@@ -106,9 +135,8 @@ describe("TelnyxProvider.verifyWebhook", () => {
     const jwk = publicKey.export({ format: "jwk" }) as JsonWebKey;
     expect(jwk.kty).toBe("OKP");
     expect(jwk.crv).toBe("Ed25519");
-    expect(typeof jwk.x).toBe("string");
 
-    const rawPublicKey = decodeBase64Url(jwk.x as string);
+    const rawPublicKey = decodeBase64Url(requireJwkX(jwk));
     const rawPublicKeyBase64 = rawPublicKey.toString("base64");
     expectWebhookVerificationSucceeds({ publicKey: rawPublicKeyBase64, privateKey });
   });
@@ -163,6 +191,150 @@ describe("TelnyxProvider.parseWebhookEvent", () => {
     );
 
     expect(result.events).toHaveLength(1);
-    expect(result.events[0]?.dedupeKey).toBe("telnyx:req:abc");
+    const event = result.events[0];
+    if (!event) {
+      throw new Error("expected Telnyx parseWebhookEvent to produce one event");
+    }
+    expect(event.dedupeKey).toBe("telnyx:req:abc");
+  });
+
+  it("maps call direction and phone numbers from Call Control callbacks", () => {
+    const provider = new TelnyxProvider({
+      apiKey: "KEY123",
+      connectionId: "CONN456",
+      publicKey: undefined,
+    });
+    const result = provider.parseWebhookEvent(
+      createCtx({
+        rawBody: JSON.stringify({
+          data: {
+            id: "evt-inbound",
+            event_type: "call.initiated",
+            payload: {
+              call_control_id: "call-1",
+              direction: "incoming",
+              from: "+15551111111",
+              to: "+15550000000",
+            },
+          },
+        }),
+      }),
+    );
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0]).toEqual(
+      expect.objectContaining({
+        type: "call.initiated",
+        direction: "inbound",
+        from: "+15551111111",
+        to: "+15550000000",
+      }),
+    );
+  });
+
+  it("reads transcription text from Telnyx transcription_data payloads", () => {
+    const provider = new TelnyxProvider({
+      apiKey: "KEY123",
+      connectionId: "CONN456",
+      publicKey: undefined,
+    });
+    const result = provider.parseWebhookEvent(
+      createCtx({
+        rawBody: JSON.stringify({
+          data: {
+            id: "evt-transcription",
+            event_type: "call.transcription",
+            payload: {
+              call_control_id: "call-1",
+              transcription_data: {
+                transcript: "hello this is a test speech",
+                is_final: false,
+                confidence: 0.977219,
+              },
+            },
+          },
+        }),
+      }),
+    );
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0]).toEqual(
+      expect.objectContaining({
+        type: "call.speech",
+        transcript: "hello this is a test speech",
+        isFinal: false,
+        confidence: 0.977219,
+      }),
+    );
+  });
+});
+
+describe("TelnyxProvider answer control", () => {
+  it("answers inbound call-control legs with a deterministic command id", async () => {
+    const release = vi.fn(async () => {});
+    apiMocks.fetchWithSsrFGuard.mockResolvedValue({
+      response: new Response(JSON.stringify({ data: {} }), { status: 200 }),
+      release,
+    });
+    const provider = new TelnyxProvider({
+      apiKey: "KEY123",
+      connectionId: "CONN456",
+      publicKey: undefined,
+    });
+
+    await provider.answerCall({
+      callId: "call-1",
+      providerCallId: "call-control-1",
+    });
+
+    expect(apiMocks.fetchWithSsrFGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "https://api.telnyx.com/v2/calls/call-control-1/actions/answer",
+        auditContext: "voice-call.telnyx.api",
+        policy: { allowedHostnames: ["api.telnyx.com"] },
+        init: expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({ command_id: "openclaw-answer-call-1" }),
+        }),
+      }),
+    );
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("TelnyxProvider speak control", () => {
+  it("passes custom Telnyx voice ids to the speak action", async () => {
+    const release = vi.fn(async () => {});
+    apiMocks.fetchWithSsrFGuard.mockResolvedValue({
+      response: new Response(JSON.stringify({ data: {} }), { status: 200 }),
+      release,
+    });
+    const provider = new TelnyxProvider({
+      apiKey: "KEY123",
+      connectionId: "CONN456",
+      publicKey: undefined,
+    });
+
+    await provider.playTts({
+      callId: "call-1",
+      providerCallId: "call-control-1",
+      text: "hello",
+      voice: "Telnyx.Qwen3TTS.12345678-1234-1234-1234-123456789abc",
+    });
+
+    expect(apiMocks.fetchWithSsrFGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "https://api.telnyx.com/v2/calls/call-control-1/actions/speak",
+        auditContext: "voice-call.telnyx.api",
+        policy: { allowedHostnames: ["api.telnyx.com"] },
+        init: expect.objectContaining({
+          method: "POST",
+          body: expect.stringContaining(
+            '"voice":"Telnyx.Qwen3TTS.12345678-1234-1234-1234-123456789abc"',
+          ),
+        }),
+      }),
+    );
+    expect(release).toHaveBeenCalledTimes(1);
   });
 });

package/src/providers/telnyx.ts

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import type { TelnyxConfig } from "../config.js";
 import type {
+  AnswerCallInput,
   EndReason,
   GetCallStatusInput,
   GetCallStatusResult,
@@ -31,6 +32,21 @@ export interface TelnyxProviderOptions {
   skipVerification?: boolean;
 }
 
+function normalizeTelnyxDirection(
+  direction: string | undefined,
+): "inbound" | "outbound" | undefined {
+  switch (direction) {
+    case "incoming":
+    case "inbound":
+      return "inbound";
+    case "outgoing":
+    case "outbound":
+      return "outbound";
+    default:
+      return undefined;
+  }
+}
+
 export class TelnyxProvider implements VoiceCallProvider {
   readonly name = "telnyx" as const;
 
@@ -143,6 +159,9 @@ export class TelnyxProvider implements VoiceCallProvider {
       callId,
       providerCallId: data.payload?.call_control_id,
       timestamp: Date.now(),
+      direction: normalizeTelnyxDirection(data.payload?.direction),
+      from: data.payload?.from,
+      to: data.payload?.to,
     };
 
     switch (data.event_type) {
@@ -169,9 +188,10 @@ export class TelnyxProvider implements VoiceCallProvider {
         return {
           ...baseEvent,
           type: "call.speech",
-          transcript: data.payload?.transcription || "",
-          isFinal: data.payload?.is_final ?? true,
-          confidence: data.payload?.confidence,
+          transcript:
+            data.payload?.transcription_data?.transcript ?? data.payload?.transcription ?? "",
+          isFinal: data.payload?.transcription_data?.is_final ?? data.payload?.is_final ?? true,
+          confidence: data.payload?.transcription_data?.confidence ?? data.payload?.confidence,
         };
 
       case "call.hangup":
@@ -261,6 +281,15 @@ export class TelnyxProvider implements VoiceCallProvider {
     );
   }
 
+  /**
+   * Answer an inbound Telnyx Call Control leg.
+   */
+  async answerCall(input: AnswerCallInput): Promise<void> {
+    await this.apiRequest(`/calls/${input.providerCallId}/actions/answer`, {
+      command_id: `openclaw-answer-${input.callId}`,
+    });
+  }
+
   /**
    * Play TTS audio via Telnyx speak action.
    */
@@ -336,10 +365,18 @@ interface TelnyxEvent {
   payload?: {
     call_control_id?: string;
     client_state?: string;
+    direction?: string;
+    from?: string;
+    to?: string;
     text?: string;
     transcription?: string;
     is_final?: boolean;
     confidence?: number;
+    transcription_data?: {
+      transcript?: string;
+      is_final?: boolean;
+      confidence?: number;
+    };
     hangup_cause?: string;
     digit?: string;
     [key: string]: unknown;

package/src/providers/twilio/api.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { fetchWithSsrFGuardMock } = vi.hoisted(() => ({
+  fetchWithSsrFGuardMock: vi.fn(),
+}));
+
+vi.mock("../../../api.js", () => ({
+  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
+}));
+
+import { TwilioApiError, twilioApiRequest } from "./api.js";
+
+describe("twilioApiRequest", () => {
+  afterEach(() => {
+    fetchWithSsrFGuardMock.mockReset();
+  });
+
+  it("posts form bodies with basic auth and parses json", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(JSON.stringify({ sid: "CA123" }), { status: 200 }),
+      release,
+    });
+
+    await expect(
+      twilioApiRequest({
+        baseUrl: "https://api.twilio.com",
+        accountSid: "AC123",
+        authToken: "secret",
+        endpoint: "/Calls.json",
+        body: {
+          To: "+14155550123",
+          StatusCallbackEvent: ["initiated", "completed"],
+        },
+      }),
+    ).resolves.toEqual({ sid: "CA123" });
+
+    const [{ url, init, auditContext, policy, timeoutMs }] =
+      fetchWithSsrFGuardMock.mock.calls[0] ?? [];
+    expect(url).toBe("https://api.twilio.com/Calls.json");
+    expect(auditContext).toBe("voice-call.twilio.api");
+    expect(policy).toEqual({ allowedHostnames: ["api.twilio.com"] });
+    expect(timeoutMs).toBe(30_000);
+    expect(init).toEqual(
+      expect.objectContaining({
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${Buffer.from("AC123:secret").toString("base64")}`,
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+      }),
+    );
+    const requestBody = init?.body;
+    if (!(requestBody instanceof URLSearchParams)) {
+      throw new Error("expected URLSearchParams request body");
+    }
+    expect(requestBody.toString()).toBe(
+      "To=%2B14155550123&StatusCallbackEvent=initiated&StatusCallbackEvent=completed",
+    );
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes through URLSearchParams, allows 404s, and returns undefined for empty bodies", async () => {
+    const responses = [
+      new Response(null, { status: 204 }),
+      new Response("missing", { status: 404 }),
+    ];
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockImplementation(async () => ({
+      response: responses.shift()!,
+      release,
+    }));
+
+    await expect(
+      twilioApiRequest({
+        baseUrl: "https://api.twilio.com",
+        accountSid: "AC123",
+        authToken: "secret",
+        endpoint: "/Calls.json",
+        body: new URLSearchParams({ To: "+14155550123" }),
+      }),
+    ).resolves.toBeUndefined();
+
+    await expect(
+      twilioApiRequest({
+        baseUrl: "https://api.twilio.com",
+        accountSid: "AC123",
+        authToken: "secret",
+        endpoint: "/Calls/missing.json",
+        body: {},
+        allowNotFound: true,
+      }),
+    ).resolves.toBeUndefined();
+    expect(release).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws twilio api errors for non-ok responses", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response("bad request", { status: 400 }),
+      release,
+    });
+
+    await expect(
+      twilioApiRequest({
+        baseUrl: "https://api.twilio.com",
+        accountSid: "AC123",
+        authToken: "secret",
+        endpoint: "/Calls.json",
+        body: {},
+      }),
+    ).rejects.toThrow("Twilio API error: 400 bad request");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("exposes structured Twilio error codes from json error bodies", async () => {
+    const release = vi.fn(async () => {});
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(
+        JSON.stringify({
+          code: 21220,
+          message: "Call is not in-progress. Cannot redirect.",
+        }),
+        { status: 400 },
+      ),
+      release,
+    });
+
+    await expect(
+      twilioApiRequest({
+        baseUrl: "https://api.twilio.com",
+        accountSid: "AC123",
+        authToken: "secret",
+        endpoint: "/Calls/CA123.json",
+        body: {},
+      }),
+    ).rejects.toMatchObject({
+      name: "TwilioApiError",
+      httpStatus: 400,
+      twilioCode: 21220,
+      message: "Twilio API error: 400 Call is not in-progress. Cannot redirect.",
+    } satisfies Partial<TwilioApiError>);
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+});

package/src/providers/twilio/api.ts

@@ -1,3 +1,44 @@
+import { fetchWithSsrFGuard } from "../../../api.js";
+
+type ParsedTwilioApiError = {
+  code?: number;
+  message?: string;
+};
+
+const TWILIO_API_TIMEOUT_MS = 30_000;
+
+function parseTwilioApiError(text: string): ParsedTwilioApiError {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object") {
+      return {};
+    }
+    const record = parsed as Record<string, unknown>;
+    return {
+      code: typeof record.code === "number" ? record.code : undefined,
+      message: typeof record.message === "string" ? record.message : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export class TwilioApiError extends Error {
+  readonly httpStatus: number;
+  readonly responseText: string;
+  readonly twilioCode?: number;
+
+  constructor(httpStatus: number, responseText: string) {
+    const parsed = parseTwilioApiError(responseText);
+    const detail = parsed.message ?? responseText;
+    super(`Twilio API error: ${httpStatus} ${detail}`);
+    this.name = "TwilioApiError";
+    this.httpStatus = httpStatus;
+    this.responseText = responseText;
+    this.twilioCode = parsed.code;
+  }
+}
+
 export async function twilioApiRequest<T = unknown>(params: {
   baseUrl: string;
   accountSid: string;
@@ -9,7 +50,7 @@ export async function twilioApiRequest<T = unknown>(params: {
   const bodyParams =
     params.body instanceof URLSearchParams
       ? params.body
-      : Object.entries(params.body).reduce<URLSearchParams>((acc, [key, value]) => {
+      : Object.entries(params.body).reduce((acc, [key, value]) => {
           if (Array.isArray(value)) {
             for (const entry of value) {
               acc.append(key, entry);
@@ -20,23 +61,33 @@ export async function twilioApiRequest<T = unknown>(params: {
           return acc;
         }, new URLSearchParams());
 
-  const response = await fetch(`${params.baseUrl}${params.endpoint}`, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${Buffer.from(`${params.accountSid}:${params.authToken}`).toString("base64")}`,
-      "Content-Type": "application/x-www-form-urlencoded",
+  const requestUrl = `${params.baseUrl}${params.endpoint}`;
+  const { response, release } = await fetchWithSsrFGuard({
+    url: requestUrl,
+    init: {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${Buffer.from(`${params.accountSid}:${params.authToken}`).toString("base64")}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: bodyParams,
     },
-    body: bodyParams,
+    policy: { allowedHostnames: ["api.twilio.com"] },
+    timeoutMs: TWILIO_API_TIMEOUT_MS,
+    auditContext: "voice-call.twilio.api",
   });
-
-  if (!response.ok) {
-    if (params.allowNotFound && response.status === 404) {
-      return undefined as T;
+  try {
+    if (!response.ok) {
+      if (params.allowNotFound && response.status === 404) {
+        return undefined as T;
+      }
+      const errorText = await response.text();
+      throw new TwilioApiError(response.status, errorText);
     }
-    const errorText = await response.text();
-    throw new Error(`Twilio API error: ${response.status} ${errorText}`);
-  }
 
-  const text = await response.text();
-  return text ? (JSON.parse(text) as T) : (undefined as T);
+    const text = await response.text();
+    return text ? (JSON.parse(text) as T) : (undefined as T);
+  } finally {
+    await release();
+  }
 }