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

package/src/media-stream.ts

@@ -3,24 +3,27 @@
  *
  * Handles bidirectional audio streaming between Twilio and the AI services.
  * - Receives mu-law audio from Twilio via WebSocket
- * - Forwards to OpenAI Realtime STT for transcription
+ * - Forwards to the selected realtime transcription provider
  * - Sends TTS audio back to Twilio
  */
 
 import type { IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";
-import { WebSocket, WebSocketServer } from "ws";
 import type {
-  OpenAIRealtimeSTTProvider,
-  RealtimeSTTSession,
-} from "./providers/stt-openai-realtime.js";
+  RealtimeTranscriptionProviderConfig,
+  RealtimeTranscriptionProviderPlugin,
+  RealtimeTranscriptionSession,
+} from "openclaw/plugin-sdk/realtime-transcription";
+import { type RawData, WebSocket, WebSocketServer } from "ws";
 
 /**
  * Configuration for the media stream handler.
  */
 export interface MediaStreamConfig {
-  /** STT provider for transcription */
-  sttProvider: OpenAIRealtimeSTTProvider;
+  /** Realtime transcription provider for streaming STT. */
+  transcriptionProvider: RealtimeTranscriptionProviderPlugin;
+  /** Provider-owned config blob passed into the transcription session. */
+  providerConfig: RealtimeTranscriptionProviderConfig;
   /** Close sockets that never send a valid `start` frame within this window. */
   preStartTimeoutMs?: number;
   /** Max concurrent pre-start sockets. */
@@ -29,6 +32,8 @@ export interface MediaStreamConfig {
   maxPendingConnectionsPerIp?: number;
   /** Max total open sockets (pending + active sessions). */
   maxConnections?: number;
+  /** Optional trusted resolver for the source IP used by pending-connection guards. */
+  resolveClientIp?: (request: IncomingMessage) => string | undefined;
   /** Validate whether to accept a media stream for the given call ID */
   shouldAcceptStream?: (params: { callId: string; streamSid: string; token?: string }) => boolean;
   /** Callback when transcript is received */
@@ -37,10 +42,12 @@ export interface MediaStreamConfig {
   onPartialTranscript?: (callId: string, partial: string) => void;
   /** Callback when stream connects */
   onConnect?: (callId: string, streamSid: string) => void;
+  /** Callback when realtime transcription is ready for the stream */
+  onTranscriptionReady?: (callId: string, streamSid: string) => void;
   /** Callback when speech starts (barge-in) */
   onSpeechStart?: (callId: string) => void;
   /** Callback when stream disconnects */
-  onDisconnect?: (callId: string) => void;
+  onDisconnect?: (callId: string, streamSid: string) => void;
 }
 
 /**
@@ -50,7 +57,7 @@ interface StreamSession {
   callId: string;
   streamSid: string;
   ws: WebSocket;
-  sttSession: RealtimeSTTSession;
+  sttSession: RealtimeTranscriptionSession;
 }
 
 type TtsQueueEntry = {
@@ -60,6 +67,13 @@ type TtsQueueEntry = {
   reject: (error: unknown) => void;
 };
 
+type StreamSendResult = {
+  sent: boolean;
+  readyState?: number;
+  bufferedBeforeBytes: number;
+  bufferedAfterBytes: number;
+};
+
 type PendingConnection = {
   ip: string;
   timeout: ReturnType<typeof setTimeout>;
@@ -69,6 +83,30 @@ const DEFAULT_PRE_START_TIMEOUT_MS = 5000;
 const DEFAULT_MAX_PENDING_CONNECTIONS = 32;
 const DEFAULT_MAX_PENDING_CONNECTIONS_PER_IP = 4;
 const DEFAULT_MAX_CONNECTIONS = 128;
+const MAX_INBOUND_MESSAGE_BYTES = 64 * 1024;
+const MAX_WS_BUFFERED_BYTES = 1024 * 1024;
+const CLOSE_REASON_LOG_MAX_CHARS = 120;
+
+export function sanitizeLogText(value: string, maxChars: number): string {
+  const sanitized = value
+    .replace(/\p{Cc}/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (sanitized.length <= maxChars) {
+    return sanitized;
+  }
+  return `${sanitized.slice(0, maxChars)}...`;
+}
+
+function normalizeWsMessageData(data: RawData): Buffer {
+  if (Buffer.isBuffer(data)) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return Buffer.concat(data);
+  }
+  return Buffer.from(data);
+}
 
 /**
  * Manages WebSocket connections for Twilio media streams.
@@ -85,6 +123,7 @@ export class MediaStreamHandler {
   private maxPendingConnections: number;
   private maxPendingConnectionsPerIp: number;
   private maxConnections: number;
+  private inflightUpgrades = 0;
   /** TTS playback queues per stream (serialize audio to prevent overlap) */
   private ttsQueues = new Map<string, TtsQueueEntry[]>();
   /** Whether TTS is currently playing per stream */
@@ -106,19 +145,50 @@ export class MediaStreamHandler {
    */
   handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): void {
     if (!this.wss) {
-      this.wss = new WebSocketServer({ noServer: true });
+      this.wss = new WebSocketServer({
+        noServer: true,
+        // Reject oversized frames before app-level parsing runs on unauthenticated sockets.
+        maxPayload: MAX_INBOUND_MESSAGE_BYTES,
+      });
       this.wss.on("connection", (ws, req) => this.handleConnection(ws, req));
     }
 
-    const currentConnections = this.wss.clients.size;
+    const currentConnections = this.getCurrentConnectionCount();
     if (currentConnections >= this.maxConnections) {
       this.rejectUpgrade(socket, 503, "Too many media stream connections");
       return;
     }
 
-    this.wss.handleUpgrade(request, socket, head, (ws) => {
-      this.wss?.emit("connection", ws, request);
-    });
+    this.inflightUpgrades += 1;
+    let released = false;
+    const releaseUpgradeReservation = () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      this.inflightUpgrades = Math.max(0, this.inflightUpgrades - 1);
+    };
+    const handleUpgradeAbort = () => {
+      socket.removeListener("error", handleUpgradeAbort);
+      socket.removeListener("close", handleUpgradeAbort);
+      releaseUpgradeReservation();
+    };
+    socket.once("error", handleUpgradeAbort);
+    socket.once("close", handleUpgradeAbort);
+
+    try {
+      this.wss.handleUpgrade(request, socket, head, (ws) => {
+        socket.removeListener("error", handleUpgradeAbort);
+        socket.removeListener("close", handleUpgradeAbort);
+        releaseUpgradeReservation();
+        this.wss?.emit("connection", ws, request);
+      });
+    } catch (error) {
+      socket.removeListener("error", handleUpgradeAbort);
+      socket.removeListener("close", handleUpgradeAbort);
+      releaseUpgradeReservation();
+      throw error;
+    }
   }
 
   /**
@@ -134,9 +204,10 @@ export class MediaStreamHandler {
       return;
     }
 
-    ws.on("message", async (data: Buffer) => {
+    ws.on("message", async (data: RawData) => {
       try {
-        const message = JSON.parse(data.toString()) as TwilioMediaMessage;
+        const raw = normalizeWsMessageData(data);
+        const message = JSON.parse(raw.toString("utf8")) as TwilioMediaMessage;
 
         switch (message.event) {
           case "connected":
@@ -144,7 +215,7 @@ export class MediaStreamHandler {
             break;
 
           case "start":
-            session = await this.handleStart(ws, message, streamToken);
+            session = this.handleStart(ws, message, streamToken);
             if (session) {
               this.clearPendingConnection(ws);
             }
@@ -164,13 +235,22 @@ export class MediaStreamHandler {
               session = null;
             }
             break;
+
+          case "clear":
+          case "mark":
+            break;
         }
       } catch (error) {
         console.error("[MediaStream] Error processing message:", error);
       }
     });
 
-    ws.on("close", () => {
+    ws.on("close", (code, reason) => {
+      const rawReason = Buffer.isBuffer(reason) ? reason.toString("utf8") : String(reason || "");
+      const reasonText = sanitizeLogText(rawReason, CLOSE_REASON_LOG_MAX_CHARS);
+      console.log(
+        `[MediaStream] WebSocket closed (code: ${code}, reason: ${reasonText || "none"})`,
+      );
       this.clearPendingConnection(ws);
       if (session) {
         this.handleStop(session);
@@ -185,11 +265,11 @@ export class MediaStreamHandler {
   /**
    * Handle stream start event.
    */
-  private async handleStart(
+  private handleStart(
     ws: WebSocket,
     message: TwilioMediaMessage,
     streamToken?: string,
-  ): Promise<StreamSession | null> {
+  ): StreamSession | null {
     const streamSid = message.streamSid || "";
     const callSid = message.start?.callSid || "";
 
@@ -213,20 +293,20 @@ export class MediaStreamHandler {
       return null;
     }
 
-    // Create STT session
-    const sttSession = this.config.sttProvider.createSession();
-
-    // Set up transcript callbacks
-    sttSession.onPartial((partial) => {
-      this.config.onPartialTranscript?.(callSid, partial);
-    });
-
-    sttSession.onTranscript((transcript) => {
-      this.config.onTranscript?.(callSid, transcript);
-    });
-
-    sttSession.onSpeechStart(() => {
-      this.config.onSpeechStart?.(callSid);
+    const sttSession = this.config.transcriptionProvider.createSession({
+      providerConfig: this.config.providerConfig,
+      onPartial: (partial) => {
+        this.config.onPartialTranscript?.(callSid, partial);
+      },
+      onTranscript: (transcript) => {
+        this.config.onTranscript?.(callSid, transcript);
+      },
+      onSpeechStart: () => {
+        this.config.onSpeechStart?.(callSid);
+      },
+      onError: (error) => {
+        console.warn("[MediaStream] Transcription session error:", error.message);
+      },
     });
 
     const session: StreamSession = {
@@ -237,18 +317,42 @@ export class MediaStreamHandler {
     };
 
     this.sessions.set(streamSid, session);
-
-    // Notify connection BEFORE STT connect so TTS can work even if STT fails
     this.config.onConnect?.(callSid, streamSid);
-
-    // Connect to OpenAI STT (non-blocking, log errors but don't fail the call)
-    sttSession.connect().catch((err) => {
-      console.warn(`[MediaStream] STT connection failed (TTS still works):`, err.message);
-    });
+    void this.connectTranscriptionAndNotify(session);
 
     return session;
   }
 
+  private async connectTranscriptionAndNotify(session: StreamSession): Promise<void> {
+    try {
+      await session.sttSession.connect();
+    } catch (error) {
+      console.warn(
+        "[MediaStream] STT connection failed; closing media stream:",
+        error instanceof Error ? error.message : String(error),
+      );
+      if (
+        this.sessions.get(session.streamSid) === session &&
+        session.ws.readyState === WebSocket.OPEN
+      ) {
+        session.ws.close(1011, "STT connection failed");
+      } else {
+        session.sttSession.close();
+      }
+      return;
+    }
+
+    if (
+      this.sessions.get(session.streamSid) !== session ||
+      session.ws.readyState !== WebSocket.OPEN
+    ) {
+      session.sttSession.close();
+      return;
+    }
+
+    this.config.onTranscriptionReady?.(session.callId, session.streamSid);
+  }
+
   /**
    * Handle stream stop event.
    */
@@ -258,7 +362,7 @@ export class MediaStreamHandler {
     this.clearTtsState(session.streamSid);
     session.sttSession.close();
     this.sessions.delete(session.streamSid);
-    this.config.onDisconnect?.(session.callId);
+    this.config.onDisconnect?.(session.callId, session.streamSid);
   }
 
   private getStreamToken(request: IncomingMessage): string | undefined {
@@ -274,9 +378,17 @@ export class MediaStreamHandler {
   }
 
   private getClientIp(request: IncomingMessage): string {
+    const resolvedIp = this.config.resolveClientIp?.(request)?.trim();
+    if (resolvedIp) {
+      return resolvedIp;
+    }
     return request.socket.remoteAddress || "unknown";
   }
 
+  private getCurrentConnectionCount(): number {
+    return this.wss ? this.wss.clients.size + this.inflightUpgrades : this.inflightUpgrades;
+  }
+
   private registerPendingConnection(ws: WebSocket, ip: string): boolean {
     if (this.pendingConnections.size >= this.maxPendingConnections) {
       console.warn("[MediaStream] Rejecting connection: pending connection limit reached");
@@ -347,17 +459,78 @@ export class MediaStreamHandler {
   /**
    * Send a message to a stream's WebSocket if available.
    */
-  private sendToStream(streamSid: string, message: unknown): void {
-    const session = this.getOpenSession(streamSid);
-    session?.ws.send(JSON.stringify(message));
+  private sendToStream(streamSid: string, message: unknown): StreamSendResult {
+    const session = this.sessions.get(streamSid);
+    if (!session) {
+      return {
+        sent: false,
+        bufferedBeforeBytes: 0,
+        bufferedAfterBytes: 0,
+      };
+    }
+
+    const readyState = session.ws.readyState;
+    const bufferedBeforeBytes = session.ws.bufferedAmount;
+    if (readyState !== WebSocket.OPEN) {
+      return {
+        sent: false,
+        readyState,
+        bufferedBeforeBytes,
+        bufferedAfterBytes: session.ws.bufferedAmount,
+      };
+    }
+    if (bufferedBeforeBytes > MAX_WS_BUFFERED_BYTES) {
+      try {
+        session.ws.close(1013, "Backpressure: send buffer exceeded");
+      } catch {
+        // Best-effort close; caller still receives sent:false.
+      }
+      return {
+        sent: false,
+        readyState,
+        bufferedBeforeBytes,
+        bufferedAfterBytes: session.ws.bufferedAmount,
+      };
+    }
+
+    try {
+      session.ws.send(JSON.stringify(message));
+      const bufferedAfterBytes = session.ws.bufferedAmount;
+      if (bufferedAfterBytes > MAX_WS_BUFFERED_BYTES) {
+        try {
+          session.ws.close(1013, "Backpressure: send buffer exceeded");
+        } catch {
+          // Best-effort close; caller still receives sent:false.
+        }
+        return {
+          sent: false,
+          readyState,
+          bufferedBeforeBytes,
+          bufferedAfterBytes,
+        };
+      }
+      return {
+        sent: true,
+        readyState,
+        bufferedBeforeBytes,
+        bufferedAfterBytes,
+      };
+    } catch {
+      return {
+        sent: false,
+        readyState,
+        bufferedBeforeBytes,
+        bufferedAfterBytes: session.ws.bufferedAmount,
+      };
+    }
   }
 
   /**
    * Send audio to a specific stream (for TTS playback).
    * Audio should be mu-law encoded at 8kHz mono.
    */
-  sendAudio(streamSid: string, muLawAudio: Buffer): void {
-    this.sendToStream(streamSid, {
+  sendAudio(streamSid: string, muLawAudio: Buffer): StreamSendResult {
+    return this.sendToStream(streamSid, {
       event: "media",
       streamSid,
       media: { payload: muLawAudio.toString("base64") },
@@ -367,8 +540,8 @@ export class MediaStreamHandler {
   /**
    * Send a mark event to track audio playback position.
    */
-  sendMark(streamSid: string, name: string): void {
-    this.sendToStream(streamSid, {
+  sendMark(streamSid: string, name: string): StreamSendResult {
+    return this.sendToStream(streamSid, {
       event: "mark",
       streamSid,
       mark: { name },
@@ -378,8 +551,8 @@ export class MediaStreamHandler {
   /**
    * Clear audio buffer (interrupt playback).
    */
-  clearAudio(streamSid: string): void {
-    this.sendToStream(streamSid, { event: "clear", streamSid });
+  clearAudio(streamSid: string): StreamSendResult {
+    return this.sendToStream(streamSid, { event: "clear", streamSid });
   }
 
   /**
@@ -412,9 +585,9 @@ export class MediaStreamHandler {
   /**
    * Clear TTS queue and interrupt current playback (barge-in).
    */
-  clearTtsQueue(streamSid: string): void {
+  clearTtsQueue(streamSid: string, _reason = "unspecified"): void {
     const queue = this.getTtsQueue(streamSid);
-    queue.length = 0;
+    this.resolveQueuedTtsEntries(queue);
     this.ttsActiveControllers.get(streamSid)?.abort();
     this.clearAudio(streamSid);
   }
@@ -487,13 +660,21 @@ export class MediaStreamHandler {
   private clearTtsState(streamSid: string): void {
     const queue = this.ttsQueues.get(streamSid);
     if (queue) {
-      queue.length = 0;
+      this.resolveQueuedTtsEntries(queue);
     }
     this.ttsActiveControllers.get(streamSid)?.abort();
     this.ttsActiveControllers.delete(streamSid);
     this.ttsPlaying.delete(streamSid);
     this.ttsQueues.delete(streamSid);
   }
+
+  private resolveQueuedTtsEntries(queue: TtsQueueEntry[]): void {
+    const pending = queue.splice(0);
+    for (const entry of pending) {
+      entry.controller.abort();
+      entry.resolve();
+    }
+  }
 }
 
 /**

package/src/providers/base.ts

@@ -1,4 +1,5 @@
 import type {
+  AnswerCallInput,
   GetCallStatusInput,
   GetCallStatusResult,
   HangupCallInput,
@@ -6,6 +7,7 @@ import type {
   InitiateCallResult,
   PlayTtsInput,
   ProviderName,
+  SendDtmfInput,
   WebhookParseOptions,
   ProviderWebhookParseResult,
   StartListeningInput,
@@ -41,12 +43,24 @@ export interface VoiceCallProvider {
    */
   parseWebhookEvent(ctx: WebhookContext, options?: WebhookParseOptions): ProviderWebhookParseResult;
 
+  /**
+   * Consume one-time TwiML that must be served before shortcut handlers such as
+   * realtime media streams take over the webhook response.
+   */
+  consumeInitialTwiML?: (ctx: WebhookContext) => string | null;
+
   /**
    * Initiate an outbound call.
    * @returns Provider call ID and status
    */
   initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
 
+  /**
+   * Answer an accepted inbound call when the provider requires an explicit
+   * answer command after the initial webhook.
+   */
+  answerCall?: (input: AnswerCallInput) => Promise<void>;
+
   /**
    * Hang up an active call.
    */
@@ -58,6 +72,11 @@ export interface VoiceCallProvider {
    */
   playTts(input: PlayTtsInput): Promise<void>;
 
+  /**
+   * Send DTMF digits to an active call.
+   */
+  sendDtmf?: (input: SendDtmfInput) => Promise<void>;
+
   /**
    * Start listening for user speech (activate STT).
    */

package/src/providers/mock.ts

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
 import type {
   EndReason,
   GetCallStatusInput,
@@ -10,6 +11,7 @@ import type {
   PlayTtsInput,
   WebhookParseOptions,
   ProviderWebhookParseResult,
+  SendDtmfInput,
   StartListeningInput,
   StopListeningInput,
   WebhookContext,
@@ -161,6 +163,10 @@ export class MockProvider implements VoiceCallProvider {
     // No-op for mock
   }
 
+  async sendDtmf(_input: SendDtmfInput): Promise<void> {
+    // No-op for mock
+  }
+
   async startListening(_input: StartListeningInput): Promise<void> {
     // No-op for mock
   }
@@ -170,7 +176,7 @@ export class MockProvider implements VoiceCallProvider {
   }
 
   async getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult> {
-    const id = input.providerCallId.toLowerCase();
+    const id = normalizeLowercaseStringOrEmpty(input.providerCallId);
     if (id.includes("stale") || id.includes("ended") || id.includes("completed")) {
       return { status: "completed", isTerminal: true };
     }

package/src/providers/plivo.test.ts

@@ -1,6 +1,20 @@
 import { describe, expect, it } from "vitest";
 import { PlivoProvider } from "./plivo.js";
 
+function requireEvent<T>(event: T | undefined, message: string): T {
+  if (!event) {
+    throw new Error(message);
+  }
+  return event;
+}
+
+function requireResponseBody(body: string | undefined): string {
+  if (!body) {
+    throw new Error("Plivo provider did not return a response body");
+  }
+  return body;
+}
+
 describe("PlivoProvider", () => {
   it("parses answer callback into call.answered and returns keep-alive XML", () => {
     const provider = new PlivoProvider({
@@ -18,11 +32,13 @@ describe("PlivoProvider", () => {
     });
 
     expect(result.events).toHaveLength(1);
-    expect(result.events[0]?.type).toBe("call.answered");
-    expect(result.events[0]?.callId).toBe("internal-call-id");
-    expect(result.events[0]?.providerCallId).toBe("call-uuid");
-    expect(result.providerResponseBody).toContain("<Wait");
-    expect(result.providerResponseBody).toContain('length="300"');
+    const event = requireEvent(result.events[0], "expected Plivo answer event");
+    expect(event.type).toBe("call.answered");
+    expect(event.callId).toBe("internal-call-id");
+    expect(event.providerCallId).toBe("call-uuid");
+    const responseBody = requireResponseBody(result.providerResponseBody);
+    expect(responseBody).toContain("<Wait");
+    expect(responseBody).toContain('length="300"');
   });
 
   it("uses verified request key when provided", () => {
@@ -44,6 +60,34 @@ describe("PlivoProvider", () => {
     );
 
     expect(result.events).toHaveLength(1);
-    expect(result.events[0]?.dedupeKey).toBe("plivo:v3:verified");
+    expect(requireEvent(result.events[0], "expected verified Plivo event").dedupeKey).toBe(
+      "plivo:v3:verified",
+    );
+  });
+
+  it("pins stored callback bases to publicUrl instead of request Host", () => {
+    const provider = new PlivoProvider(
+      {
+        authId: "MA000000000000000000",
+        authToken: "test-token",
+      },
+      {
+        publicUrl: "https://voice.openclaw.ai/voice/webhook?provider=plivo",
+      },
+    );
+
+    provider.parseWebhookEvent({
+      headers: { host: "attacker.example" },
+      rawBody:
+        "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
+      url: "https://attacker.example/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
+      method: "POST",
+      query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
+    });
+
+    const callbackMap = (provider as unknown as { callUuidToWebhookUrl: Map<string, string> })
+      .callUuidToWebhookUrl;
+
+    expect(callbackMap.get("call-uuid")).toBe("https://voice.openclaw.ai/voice/webhook");
   });
 });

package/src/providers/plivo.ts

@@ -1,4 +1,8 @@
 import crypto from "node:crypto";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
 import type { PlivoConfig, WebhookSecurityConfig } from "../config.js";
 import { getHeader } from "../http-headers.js";
 import type {
@@ -129,7 +133,7 @@ export class PlivoProvider implements VoiceCallProvider {
     ctx: WebhookContext,
     options?: WebhookParseOptions,
   ): ProviderWebhookParseResult {
-    const flow = typeof ctx.query?.flow === "string" ? ctx.query.flow.trim() : "";
+    const flow = normalizeOptionalString(ctx.query?.flow) ?? "";
 
     const parsed = this.parseBody(ctx.rawBody);
     if (!parsed) {
@@ -480,7 +484,7 @@ export class PlivoProvider implements VoiceCallProvider {
 
   private static normalizeNumber(numberOrSip: string): string {
     const trimmed = numberOrSip.trim();
-    if (trimmed.toLowerCase().startsWith("sip:")) {
+    if (normalizeLowercaseStringOrEmpty(trimmed).startsWith("sip:")) {
       return trimmed;
     }
     return trimmed.replace(/[^\d+]/g, "");
@@ -517,10 +521,7 @@ export class PlivoProvider implements VoiceCallProvider {
   }
 
   private getCallIdFromQuery(ctx: WebhookContext): string | undefined {
-    const callId =
-      typeof ctx.query?.callId === "string" && ctx.query.callId.trim()
-        ? ctx.query.callId.trim()
-        : undefined;
+    const callId = normalizeOptionalString(ctx.query?.callId);
     return callId || undefined;
   }
 
@@ -544,6 +545,13 @@ export class PlivoProvider implements VoiceCallProvider {
 
   private baseWebhookUrlFromCtx(ctx: WebhookContext): string | null {
     try {
+      if (this.options.publicUrl) {
+        const base = new URL(this.options.publicUrl);
+        const requestUrl = new URL(ctx.url);
+        base.pathname = requestUrl.pathname;
+        return `${base.origin}${base.pathname}`;
+      }
+
       const u = new URL(
         reconstructWebhookUrl(ctx, {
           allowedHosts: this.options.webhookSecurity?.allowedHosts,