twilio-agent-connect 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -1649,6 +1649,19 @@ declare const InterruptMessageSchema: z.ZodObject<{
     durationUntilInterruptMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 type InterruptMessage = z.infer<typeof InterruptMessageSchema>;
+/**
+ * WebSocket DTMF message (caller pressed a key).
+ *
+ * Only sent when `dtmfDetection` is enabled on `<ConversationRelay>`, and one
+ * message per keypress — digits are never batched.
+ *
+ * @see https://www.twilio.com/docs/voice/conversationrelay/websocket-messages#dtmf-message
+ */
+declare const DtmfMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dtmf">;
+    digit: z.ZodString;
+}, z.core.$strip>;
+type DtmfMessage = z.infer<typeof DtmfMessageSchema>;
 /**
  * Union of all WebSocket message types
  */
@@ -1676,6 +1689,9 @@ declare const WebSocketMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"interrupt">;
     utteranceUntilInterrupt: z.ZodOptional<z.ZodString>;
     durationUntilInterruptMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"dtmf">;
+    digit: z.ZodString;
 }, z.core.$strip>]>;
 type WebSocketMessage = z.infer<typeof WebSocketMessageSchema>;
 /**
@@ -3532,6 +3548,22 @@ type CallStatusHandler = (event: CallStatusEvent) => Promise<void> | void;
 type AmdHandler = (event: AmdEvent) => Promise<void> | void;
 /** Handler for Twilio `recordingStatusCallback` webhooks. */
 type RecordingHandler = (event: RecordingEvent) => Promise<void> | void;
+/** One ConversationRelay keypress, as delivered to a {@link DtmfHandler}. */
+interface DtmfEvent {
+    /**
+     * Undefined only when the keypress beat conversation setup: `dtmf` before
+     * ConversationRelay's `setup`, or an orchestrated-mode lookup that failed.
+     */
+    conversationId: ConversationId | undefined;
+    /** Undefined only before ConversationRelay's `setup` message. */
+    callSid: string | undefined;
+    /** The key pressed: `0`-`9`, `*`, `#`, or `A`-`D`. */
+    digit: string;
+    /** Present whenever `conversationId` is. */
+    session?: ConversationSession;
+}
+/** Handler for ConversationRelay `dtmf` messages (caller keypresses). */
+type DtmfHandler = (event: DtmfEvent) => Promise<void> | void;
 /**
  * Voice channel event callbacks extending base callbacks
  */
@@ -3554,6 +3586,8 @@ interface VoiceChannelEvents extends BaseChannelEvents {
         utteranceUntilInterrupt: string | undefined;
         durationUntilInterruptMs: number | undefined;
     }) => void;
+    /** Caller keypress. See {@link VoiceChannel.onDtmf}. */
+    onDtmf?: DtmfHandler;
     /**
      * Fired once the session and WebSocket registration exist — in orchestrated
      * mode possibly before the first prompt, since the lookup starts at setup.
@@ -3675,6 +3709,30 @@ declare class VoiceChannel extends BaseChannel {
      * ```
      */
     onRecording(callback: RecordingHandler): void;
+    /**
+     * Register a handler for DTMF keypresses, called once per key in order.
+     *
+     * Requires `dtmfDetection: true` on the ConversationRelay config — without it
+     * Twilio sends nothing and this never fires. Digits aren't buffered, so
+     * accumulating a multi-digit entry is the handler's job.
+     *
+     * A keypress initializes the conversation just as a prompt does, since a
+     * caller can type without ever speaking; if that fails the digit still
+     * arrives, with `conversationId` and `session` undefined. Keypresses don't
+     * cancel in-flight streaming on their own — that's a separate `interrupt`
+     * message, sent when `interruptible` includes `dtmf`.
+     *
+     * @example
+     * ```typescript
+     * const digits = new Map<string, string>();
+     *
+     * voiceChannel.onDtmf(({ conversationId, digit }) => {
+     *   if (!conversationId) return;
+     *   digits.set(conversationId, (digits.get(conversationId) ?? '') + digit);
+     * });
+     * ```
+     */
+    onDtmf(callback: DtmfHandler): void;
     /**
      * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
      * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
@@ -3734,6 +3792,10 @@ declare class VoiceChannel extends BaseChannel {
      * Handle WebSocket interrupt message
      */
     private handleInterruptMessage;
+    /**
+     * Handle WebSocket DTMF message (caller keypress)
+     */
+    private handleDtmfMessage;
     /**
      * Handle WebSocket disconnection. In orchestrated mode the conversation stays
      * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
@@ -4650,4 +4712,4 @@ declare class TACServer {
     stop(): Promise<void>;
 }
 
-export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AmdEvent, AmdEventSchema, type AmdHandler, type AnthropicTool, AnthropicToolSchema, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, CALL_EVENT_KINDS, type CallEventKind, CallEventKindSchema, type CallOptions, CallOptionsSchema, type CallStatusEvent, CallStatusEventSchema, type CallStatusHandler, type CaptureRule, CaptureRuleSchema, type ChannelSettings, ChannelSettingsSchema, type ChannelType, ChannelTypeSchema, ChatChannel, type ChatChannelConfig, type CintelParticipant, CintelParticipantSchema, type Communication, type CommunicationContent, CommunicationContentSchema, type CommunicationParticipant, CommunicationParticipantSchema, CommunicationSchema, type ConversationAddress, ConversationAddressSchema, ConversationClient, type ConversationConfiguration, ConversationConfigurationSchema, type ConversationEndedCallback, type ConversationGroupingType, ConversationGroupingTypeSchema, type ConversationId, type ConversationIntelligenceConfig, ConversationIntelligenceConfigSchema, type ConversationParticipant, ConversationParticipantSchema, type ConversationRelayAttributes, ConversationRelayAttributesSchema, type ConversationRelayCallbackPayload, ConversationRelayCallbackPayloadSchema, type ConversationRelayConfig, ConversationRelayConfigSchema, type ConversationResponse, ConversationResponseSchema, type ConversationSession, ConversationSessionSchema, type ConversationSummaryItem, ConversationSummaryItemSchema, type ConversationWebhookPayload, type CreateConversationSummariesResponse, CreateConversationSummariesResponseSchema, type CreateObservationResponse, CreateObservationResponseSchema, type CreateObservationsRequest, CreateObservationsRequestSchema, type CustomParameters, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type InterruptMode, InterruptModeSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, type LanguageConfig, LanguageConfigSchema, type ListCommunicationsResponse, ListCommunicationsResponseSchema, type ListConversationsResponse, ListConversationsResponseSchema, type ListParticipantsResponse, ListParticipantsResponseSchema, type Logger, type MemoryChannelType, MemoryChannelTypeSchema, MemoryClient, type MemoryCommunication, type MemoryCommunicationContent, MemoryCommunicationContentSchema, MemoryCommunicationSchema, type MemoryDeliveryStatus, MemoryDeliveryStatusSchema, type MemoryMode, MemoryModeSchema, type MemoryParticipant, MemoryParticipantSchema, type MemoryParticipantType, MemoryParticipantTypeSchema, MemoryPromptBuilder, type MemoryRetrievalRequest, MemoryRetrievalRequestSchema, type MemoryRetrievalResponse, MemoryRetrievalResponseSchema, type MessageDirection, MessageDirectionSchema, type MessageReadyCallback, MessagingChannel, type MessagingChannelConfig, type MessagingChannelEvents, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, type OpenAITool, OpenAIToolSchema, type Operator, type OperatorProcessingResult, OperatorProcessingResultSchema, type OperatorResult, type OperatorResultEvent, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, type ParticipantAddress, ParticipantAddressSchema, type ParticipantAddressType, ParticipantAddressTypeSchema, type ParticipantId, type PendingHandoffData, PendingHandoffDataSchema, type Profile, type ProfileId, type ProfileLookupResponse, ProfileLookupResponseSchema, type ProfileResponse, ProfileResponseSchema, type PromptMessage, PromptMessageSchema, RCSChannel, type RecordingEvent, RecordingEventSchema, type RecordingHandler, SMSChannel, type SendMessageActionPayload, SendMessageActionPayloadSchema, type SendMessageActionRequest, SendMessageActionRequestSchema, type SessionInfo, SessionInfoSchema, type SessionMessage, SessionMessageSchema, type SetupMessage, SetupMessageSchema, type StatusCallback, StatusCallbackSchema, type StatusTimeouts, StatusTimeoutsSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
+export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AmdEvent, AmdEventSchema, type AmdHandler, type AnthropicTool, AnthropicToolSchema, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, CALL_EVENT_KINDS, type CallEventKind, CallEventKindSchema, type CallOptions, CallOptionsSchema, type CallStatusEvent, CallStatusEventSchema, type CallStatusHandler, type CaptureRule, CaptureRuleSchema, type ChannelSettings, ChannelSettingsSchema, type ChannelType, ChannelTypeSchema, ChatChannel, type ChatChannelConfig, type CintelParticipant, CintelParticipantSchema, type Communication, type CommunicationContent, CommunicationContentSchema, type CommunicationParticipant, CommunicationParticipantSchema, CommunicationSchema, type ConversationAddress, ConversationAddressSchema, ConversationClient, type ConversationConfiguration, ConversationConfigurationSchema, type ConversationEndedCallback, type ConversationGroupingType, ConversationGroupingTypeSchema, type ConversationId, type ConversationIntelligenceConfig, ConversationIntelligenceConfigSchema, type ConversationParticipant, ConversationParticipantSchema, type ConversationRelayAttributes, ConversationRelayAttributesSchema, type ConversationRelayCallbackPayload, ConversationRelayCallbackPayloadSchema, type ConversationRelayConfig, ConversationRelayConfigSchema, type ConversationResponse, ConversationResponseSchema, type ConversationSession, ConversationSessionSchema, type ConversationSummaryItem, ConversationSummaryItemSchema, type ConversationWebhookPayload, type CreateConversationSummariesResponse, CreateConversationSummariesResponseSchema, type CreateObservationResponse, CreateObservationResponseSchema, type CreateObservationsRequest, CreateObservationsRequestSchema, type CustomParameters, CustomParametersSchema, type DtmfEvent, type DtmfHandler, type DtmfMessage, DtmfMessageSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type InterruptMode, InterruptModeSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, type LanguageConfig, LanguageConfigSchema, type ListCommunicationsResponse, ListCommunicationsResponseSchema, type ListConversationsResponse, ListConversationsResponseSchema, type ListParticipantsResponse, ListParticipantsResponseSchema, type Logger, type MemoryChannelType, MemoryChannelTypeSchema, MemoryClient, type MemoryCommunication, type MemoryCommunicationContent, MemoryCommunicationContentSchema, MemoryCommunicationSchema, type MemoryDeliveryStatus, MemoryDeliveryStatusSchema, type MemoryMode, MemoryModeSchema, type MemoryParticipant, MemoryParticipantSchema, type MemoryParticipantType, MemoryParticipantTypeSchema, MemoryPromptBuilder, type MemoryRetrievalRequest, MemoryRetrievalRequestSchema, type MemoryRetrievalResponse, MemoryRetrievalResponseSchema, type MessageDirection, MessageDirectionSchema, type MessageReadyCallback, MessagingChannel, type MessagingChannelConfig, type MessagingChannelEvents, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, type OpenAITool, OpenAIToolSchema, type Operator, type OperatorProcessingResult, OperatorProcessingResultSchema, type OperatorResult, type OperatorResultEvent, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, type ParticipantAddress, ParticipantAddressSchema, type ParticipantAddressType, ParticipantAddressTypeSchema, type ParticipantId, type PendingHandoffData, PendingHandoffDataSchema, type Profile, type ProfileId, type ProfileLookupResponse, ProfileLookupResponseSchema, type ProfileResponse, ProfileResponseSchema, type PromptMessage, PromptMessageSchema, RCSChannel, type RecordingEvent, RecordingEventSchema, type RecordingHandler, SMSChannel, type SendMessageActionPayload, SendMessageActionPayloadSchema, type SendMessageActionRequest, SendMessageActionRequestSchema, type SessionInfo, SessionInfoSchema, type SessionMessage, SessionMessageSchema, type SetupMessage, SetupMessageSchema, type StatusCallback, StatusCallbackSchema, type StatusTimeouts, StatusTimeoutsSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };

package/dist/index.js

@@ -769,10 +769,16 @@ var InterruptMessageSchema = z.object({
   utteranceUntilInterrupt: z.string().optional(),
   durationUntilInterruptMs: z.number().int().nonnegative().optional()
 });
+var DtmfMessageSchema = z.object({
+  type: z.literal("dtmf"),
+  /** The key pressed: `0`-`9`, `*`, `#`, or `A`-`D`. */
+  digit: z.string()
+});
 var WebSocketMessageSchema = z.union([
   SetupMessageSchema,
   PromptMessageSchema,
-  InterruptMessageSchema
+  InterruptMessageSchema,
+  DtmfMessageSchema
 ]);
 var TextTokenMessageSchema = z.object({
   type: z.literal("text"),
@@ -1681,7 +1687,7 @@ function createLogger(options) {
 
 // package.json
 var package_default = {
-  version: "2.2.0"};
+  version: "2.3.0"};
 function buildUserAgent() {
   return `twilio-agent-connect-typescript/${package_default.version}`;
 }
@@ -4803,6 +4809,32 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   onRecording(callback) {
     this.onRecordingHandler = callback;
   }
+  /**
+   * Register a handler for DTMF keypresses, called once per key in order.
+   *
+   * Requires `dtmfDetection: true` on the ConversationRelay config — without it
+   * Twilio sends nothing and this never fires. Digits aren't buffered, so
+   * accumulating a multi-digit entry is the handler's job.
+   *
+   * A keypress initializes the conversation just as a prompt does, since a
+   * caller can type without ever speaking; if that fails the digit still
+   * arrives, with `conversationId` and `session` undefined. Keypresses don't
+   * cancel in-flight streaming on their own — that's a separate `interrupt`
+   * message, sent when `interruptible` includes `dtmf`.
+   *
+   * @example
+   * ```typescript
+   * const digits = new Map<string, string>();
+   *
+   * voiceChannel.onDtmf(({ conversationId, digit }) => {
+   *   if (!conversationId) return;
+   *   digits.set(conversationId, (digits.get(conversationId) ?? '') + digit);
+   * });
+   * ```
+   */
+  onDtmf(callback) {
+    this.voiceCallbacks.onDtmf = callback;
+  }
   /**
    * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
    * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
@@ -4854,6 +4886,9 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       case "interrupt":
         this.voiceCallbacks.onInterrupt = callback;
         break;
+      case "dtmf":
+        this.voiceCallbacks.onDtmf = callback;
+        break;
       case "webSocketConnected":
         this.voiceCallbacks.onWebSocketConnected = callback;
         break;
@@ -4994,6 +5029,64 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
     let fromNumber = null;
     let initializationFailed = false;
     let initPromise = null;
+    const ensureConversation = async () => {
+      if (conversationId) {
+        return conversationId;
+      }
+      const sid = callSid;
+      if (!sid) {
+        return null;
+      }
+      const retryCount = this.initializationRetries.get(sid) ?? 0;
+      if (retryCount >= this.MAX_INITIALIZATION_RETRIES) {
+        throw new Error(
+          `Cannot process message - conversation initialization failed after ${retryCount} attempts for callSid ${sid}`
+        );
+      }
+      try {
+        if (initializationFailed) {
+          this.logger.info(
+            { call_sid: sid, retry_count: retryCount },
+            "Retrying conversation initialization after previous failure"
+          );
+        }
+        if (!this.tac.isOrchestratorEnabled()) {
+          conversationId = sid;
+          this.webSocketConnections.set(conversationId, ws);
+          this.callSidToConversationId.set(sid, conversationId);
+          const session = this.startConversation(conversationId);
+          session.callSid = sid;
+          if (fromNumber) {
+            session.authorInfo = { address: fromNumber };
+          }
+          if (this.voiceCallbacks.onWebSocketConnected) {
+            this.voiceCallbacks.onWebSocketConnected({ conversationId });
+          }
+        } else {
+          initPromise ??= this.initializeOrchestratedConversation(sid, fromNumber, ws);
+          try {
+            conversationId = await initPromise;
+          } finally {
+            initPromise = null;
+          }
+        }
+        initializationFailed = false;
+        this.initializationRetries.delete(sid);
+        this.logger.info(
+          { conversation_id: conversationId, call_sid: sid },
+          "Conversation initialization succeeded"
+        );
+        return conversationId;
+      } catch (err) {
+        initializationFailed = true;
+        this.initializationRetries.set(sid, retryCount + 1);
+        this.logger.error(
+          { err, call_sid: sid, retry_count: retryCount + 1 },
+          "Conversation initialization failed"
+        );
+        throw err;
+      }
+    };
     ws.on("message", (data) => {
       (async () => {
         try {
@@ -5034,60 +5127,7 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
               }
               break;
             case "prompt":
-              if (!conversationId && callSid) {
-                const retryCount = this.initializationRetries.get(callSid) ?? 0;
-                if (retryCount >= this.MAX_INITIALIZATION_RETRIES) {
-                  throw new Error(
-                    `Cannot process prompt - conversation initialization failed after ${retryCount} attempts for callSid ${callSid}`
-                  );
-                }
-                try {
-                  if (initializationFailed) {
-                    this.logger.info(
-                      { call_sid: callSid, retry_count: retryCount },
-                      "Retrying conversation initialization after previous failure"
-                    );
-                  }
-                  if (!this.tac.isOrchestratorEnabled()) {
-                    conversationId = callSid;
-                    this.webSocketConnections.set(conversationId, ws);
-                    this.callSidToConversationId.set(callSid, conversationId);
-                    const session = this.startConversation(conversationId);
-                    session.callSid = callSid;
-                    if (fromNumber) {
-                      session.authorInfo = { address: fromNumber };
-                    }
-                    if (this.voiceCallbacks.onWebSocketConnected) {
-                      this.voiceCallbacks.onWebSocketConnected({ conversationId });
-                    }
-                  } else {
-                    initPromise ??= this.initializeOrchestratedConversation(
-                      callSid,
-                      fromNumber,
-                      ws
-                    );
-                    try {
-                      conversationId = await initPromise;
-                    } finally {
-                      initPromise = null;
-                    }
-                  }
-                  initializationFailed = false;
-                  this.initializationRetries.delete(callSid);
-                  this.logger.info(
-                    { conversation_id: conversationId, call_sid: callSid },
-                    "Conversation initialization succeeded"
-                  );
-                } catch (err) {
-                  initializationFailed = true;
-                  this.initializationRetries.set(callSid, retryCount + 1);
-                  this.logger.error(
-                    { err, call_sid: callSid, retry_count: retryCount + 1 },
-                    "Conversation initialization failed"
-                  );
-                  throw err;
-                }
-              }
+              await ensureConversation();
               if (conversationId) {
                 const previousPrompt = this.promptQueues.get(conversationId) ?? Promise.resolve();
                 const currentPrompt = previousPrompt.then(() => this.handlePromptMessage(conversationId, message)).catch((err) => {
@@ -5106,6 +5146,17 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
                 this.handleInterruptMessage(conversationId, message);
               }
               break;
+            case "dtmf":
+              try {
+                await ensureConversation();
+              } catch (err) {
+                this.logger.warn(
+                  { err, call_sid: callSid },
+                  "Conversation initialization failed on DTMF keypress, delivering digit without a conversation"
+                );
+              }
+              await this.handleDtmfMessage(conversationId, callSid, message);
+              break;
             default:
               this.logger.debug(
                 {
@@ -5211,6 +5262,23 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       });
     }
   }
+  /**
+   * Handle WebSocket DTMF message (caller keypress)
+   */
+  async handleDtmfMessage(conversationId, callSid, message) {
+    const { digit } = message;
+    this.logger.debug({ conversation_id: conversationId, call_sid: callSid }, "DTMF keypress");
+    if (!this.voiceCallbacks.onDtmf) {
+      return;
+    }
+    const session = conversationId ? this.getConversationSession(conversationId) : void 0;
+    await this.voiceCallbacks.onDtmf({
+      conversationId: conversationId ?? void 0,
+      callSid: callSid ?? void 0,
+      digit,
+      ...session !== void 0 && { session }
+    });
+  }
   /**
    * Handle WebSocket disconnection. In orchestrated mode the conversation stays
    * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
@@ -7016,6 +7084,6 @@ var TACServer = class {
   }
 };
 
-export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AmdEventSchema, AnthropicToolSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CALL_EVENT_KINDS, CallEventKindSchema, CallOptionsSchema, CallStatusEventSchema, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CreateObservationsRequestSchema, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, ExecutionDetailsSchema, HandoffPayloadSchema, InitiateMessagingConversationOptionsSchema, InitiateVoiceConversationOptionsSchema, IntelligenceConfigurationSchema, InterruptMessageSchema, InterruptModeSchema, JSONSchemaSchema, KnowledgeBaseSchema, KnowledgeBaseStatusSchema, KnowledgeChunkResultSchema, KnowledgeClient, KnowledgeSearchResponseSchema, LanguageAttributesSchema, LanguageConfigSchema, ListCommunicationsResponseSchema, ListConversationsResponseSchema, ListParticipantsResponseSchema, MemoryChannelTypeSchema, MemoryClient, MemoryCommunicationContentSchema, MemoryCommunicationSchema, MemoryDeliveryStatusSchema, MemoryModeSchema, MemoryParticipantSchema, MemoryParticipantTypeSchema, MemoryPromptBuilder, MemoryRetrievalRequestSchema, MemoryRetrievalResponseSchema, MessageDirectionSchema, MessagingChannel, ObservationCreateRequestSchema, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, RecordingEventSchema, SMSChannel, SendMessageActionPayloadSchema, SendMessageActionRequestSchema, SessionInfoSchema, SessionMessageSchema, SetupMessageSchema, StatusCallbackSchema, StatusTimeoutsSchema, SummaryInfoSchema, TAC, TACChannelTypeSchema, TACCommunicationAuthorSchema, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, TACConfigSchema, TACDeliveryStatusSchema, TACMemoryResponse, TACParticipantTypeSchema, TACServer, TACTool, TextTokenMessageSchema, ToolExecutionResultSchema, TranscriptionSchema, TranscriptionWordSchema, TwiMLOptionsSchema, TwiMLRequestSchema, TwilioMemoryConfigSchema, VoiceChannel, WebSocketMessageSchema, WhatsAppChannel, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
+export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AmdEventSchema, AnthropicToolSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CALL_EVENT_KINDS, CallEventKindSchema, CallOptionsSchema, CallStatusEventSchema, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CreateObservationsRequestSchema, CustomParametersSchema, DtmfMessageSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, ExecutionDetailsSchema, HandoffPayloadSchema, InitiateMessagingConversationOptionsSchema, InitiateVoiceConversationOptionsSchema, IntelligenceConfigurationSchema, InterruptMessageSchema, InterruptModeSchema, JSONSchemaSchema, KnowledgeBaseSchema, KnowledgeBaseStatusSchema, KnowledgeChunkResultSchema, KnowledgeClient, KnowledgeSearchResponseSchema, LanguageAttributesSchema, LanguageConfigSchema, ListCommunicationsResponseSchema, ListConversationsResponseSchema, ListParticipantsResponseSchema, MemoryChannelTypeSchema, MemoryClient, MemoryCommunicationContentSchema, MemoryCommunicationSchema, MemoryDeliveryStatusSchema, MemoryModeSchema, MemoryParticipantSchema, MemoryParticipantTypeSchema, MemoryPromptBuilder, MemoryRetrievalRequestSchema, MemoryRetrievalResponseSchema, MessageDirectionSchema, MessagingChannel, ObservationCreateRequestSchema, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, RecordingEventSchema, SMSChannel, SendMessageActionPayloadSchema, SendMessageActionRequestSchema, SessionInfoSchema, SessionMessageSchema, SetupMessageSchema, StatusCallbackSchema, StatusTimeoutsSchema, SummaryInfoSchema, TAC, TACChannelTypeSchema, TACCommunicationAuthorSchema, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, TACConfigSchema, TACDeliveryStatusSchema, TACMemoryResponse, TACParticipantTypeSchema, TACServer, TACTool, TextTokenMessageSchema, ToolExecutionResultSchema, TranscriptionSchema, TranscriptionWordSchema, TwiMLOptionsSchema, TwiMLRequestSchema, TwilioMemoryConfigSchema, VoiceChannel, WebSocketMessageSchema, WhatsAppChannel, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map