twilio-agent-connect 1.0.3 → 2.0.0

package/dist/index.d.ts

@@ -51,7 +51,9 @@ declare const TACConfigSchema: z.ZodObject<{
         phoneTraitField: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     conversationConfigurationId: z.ZodOptional<z.ZodString>;
-    voicePublicDomain: z.ZodOptional<z.ZodString>;
+    voicePublicDomain: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
+    voiceWebsocketPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    voiceActionPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
     cintelConfigurationId: z.ZodOptional<z.ZodString>;
     cintelObservationOperatorSid: z.ZodOptional<z.ZodString>;
     cintelSummaryOperatorSid: z.ZodOptional<z.ZodString>;
@@ -79,6 +81,8 @@ declare const EnvironmentVariables: {
     readonly TWILIO_MEMORY_PHONE_TRAIT_FIELD: "TWILIO_MEMORY_PHONE_TRAIT_FIELD";
     readonly TWILIO_CONVERSATION_CONFIGURATION_ID: "TWILIO_CONVERSATION_CONFIGURATION_ID";
     readonly TWILIO_VOICE_PUBLIC_DOMAIN: "TWILIO_VOICE_PUBLIC_DOMAIN";
+    readonly TWILIO_VOICE_WEBSOCKET_PATH: "TWILIO_VOICE_WEBSOCKET_PATH";
+    readonly TWILIO_VOICE_ACTION_PATH: "TWILIO_VOICE_ACTION_PATH";
     readonly TWILIO_TAC_CI_CONFIGURATION_ID: "TWILIO_TAC_CI_CONFIGURATION_ID";
     readonly TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID: "TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID";
     readonly TWILIO_TAC_CI_SUMMARY_OPERATOR_SID: "TWILIO_TAC_CI_SUMMARY_OPERATOR_SID";
@@ -87,11 +91,17 @@ declare const EnvironmentVariables: {
 };
 
 /**
- * Memory retrieval mode for channels
+ * Memory retrieval mode for channels.
+ *
+ * - "always": Fetch memory with the message as query on every inbound message.
+ * - "once": Fetch memory once at conversation start with an empty query and
+ *   cache it. The cache is invalidated when the conversation becomes INACTIVE.
+ * - "never": Never automatically fetch memory (default).
  */
 declare const MemoryModeSchema: z.ZodEnum<{
     never: "never";
     always: "always";
+    once: "once";
 }>;
 type MemoryMode = z.infer<typeof MemoryModeSchema>;
 /**
@@ -470,6 +480,267 @@ declare const CreateConversationSummariesResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type CreateConversationSummariesResponse = z.infer<typeof CreateConversationSummariesResponseSchema>;
 
+/**
+ * Channel type for communications
+ */
+declare const TACChannelTypeSchema: z.ZodEnum<{
+    VOICE: "VOICE";
+    SMS: "SMS";
+    RCS: "RCS";
+    EMAIL: "EMAIL";
+    WHATSAPP: "WHATSAPP";
+    CHAT: "CHAT";
+    API: "API";
+    SYSTEM: "SYSTEM";
+}>;
+type TACChannelType = z.infer<typeof TACChannelTypeSchema>;
+/**
+ * Delivery status for communications
+ */
+declare const TACDeliveryStatusSchema: z.ZodEnum<{
+    INITIATED: "INITIATED";
+    IN_PROGRESS: "IN_PROGRESS";
+    DELIVERED: "DELIVERED";
+    COMPLETED: "COMPLETED";
+    FAILED: "FAILED";
+}>;
+type TACDeliveryStatus = z.infer<typeof TACDeliveryStatusSchema>;
+/**
+ * Participant type
+ */
+declare const TACParticipantTypeSchema: z.ZodEnum<{
+    HUMAN_AGENT: "HUMAN_AGENT";
+    CUSTOMER: "CUSTOMER";
+    AI_AGENT: "AI_AGENT";
+    AGENT: "AGENT";
+}>;
+type TACParticipantType = z.infer<typeof TACParticipantTypeSchema>;
+/**
+ * Unified author model with all fields from both Memory and Conversation Orchestrator APIs.
+ *
+ * Fields not available from a particular API will be undefined.
+ */
+declare const TACCommunicationAuthorSchema: z.ZodObject<{
+    address: z.ZodString;
+    channel: z.ZodEnum<{
+        VOICE: "VOICE";
+        SMS: "SMS";
+        RCS: "RCS";
+        EMAIL: "EMAIL";
+        WHATSAPP: "WHATSAPP";
+        CHAT: "CHAT";
+        API: "API";
+        SYSTEM: "SYSTEM";
+    }>;
+    participantId: z.ZodOptional<z.ZodString>;
+    deliveryStatus: z.ZodOptional<z.ZodEnum<{
+        INITIATED: "INITIATED";
+        IN_PROGRESS: "IN_PROGRESS";
+        DELIVERED: "DELIVERED";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+    }>>;
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        HUMAN_AGENT: "HUMAN_AGENT";
+        CUSTOMER: "CUSTOMER";
+        AI_AGENT: "AI_AGENT";
+        AGENT: "AGENT";
+    }>>;
+    profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type TACCommunicationAuthor = z.infer<typeof TACCommunicationAuthorSchema>;
+/**
+ * Unified content model with all fields from both Memory and Conversation Orchestrator APIs.
+ */
+declare const TACCommunicationContentSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        TEXT: "TEXT";
+        TRANSCRIPTION: "TRANSCRIPTION";
+    }>>;
+    text: z.ZodOptional<z.ZodString>;
+    transcription: z.ZodOptional<z.ZodObject<{
+        channel: z.ZodOptional<z.ZodNumber>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        engine: z.ZodOptional<z.ZodString>;
+        words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            startTime: z.ZodOptional<z.ZodString>;
+            endTime: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type TACCommunicationContent = z.infer<typeof TACCommunicationContentSchema>;
+/**
+ * Unified communication model with all fields from both Memory and Conversation Orchestrator APIs.
+ *
+ * Provides complete access to all communication fields regardless of the source.
+ * Fields not available from a particular API will be undefined.
+ */
+declare const TACCommunicationSchema: z.ZodObject<{
+    id: z.ZodString;
+    author: z.ZodObject<{
+        address: z.ZodString;
+        channel: z.ZodEnum<{
+            VOICE: "VOICE";
+            SMS: "SMS";
+            RCS: "RCS";
+            EMAIL: "EMAIL";
+            WHATSAPP: "WHATSAPP";
+            CHAT: "CHAT";
+            API: "API";
+            SYSTEM: "SYSTEM";
+        }>;
+        participantId: z.ZodOptional<z.ZodString>;
+        deliveryStatus: z.ZodOptional<z.ZodEnum<{
+            INITIATED: "INITIATED";
+            IN_PROGRESS: "IN_PROGRESS";
+            DELIVERED: "DELIVERED";
+            COMPLETED: "COMPLETED";
+            FAILED: "FAILED";
+        }>>;
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<{
+            HUMAN_AGENT: "HUMAN_AGENT";
+            CUSTOMER: "CUSTOMER";
+            AI_AGENT: "AI_AGENT";
+            AGENT: "AGENT";
+        }>>;
+        profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    content: z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<{
+            TEXT: "TEXT";
+            TRANSCRIPTION: "TRANSCRIPTION";
+        }>>;
+        text: z.ZodOptional<z.ZodString>;
+        transcription: z.ZodOptional<z.ZodObject<{
+            channel: z.ZodOptional<z.ZodNumber>;
+            confidence: z.ZodOptional<z.ZodNumber>;
+            engine: z.ZodOptional<z.ZodString>;
+            words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                startTime: z.ZodOptional<z.ZodString>;
+                endTime: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    recipients: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        channel: z.ZodEnum<{
+            VOICE: "VOICE";
+            SMS: "SMS";
+            RCS: "RCS";
+            EMAIL: "EMAIL";
+            WHATSAPP: "WHATSAPP";
+            CHAT: "CHAT";
+            API: "API";
+            SYSTEM: "SYSTEM";
+        }>;
+        participantId: z.ZodOptional<z.ZodString>;
+        deliveryStatus: z.ZodOptional<z.ZodEnum<{
+            INITIATED: "INITIATED";
+            IN_PROGRESS: "IN_PROGRESS";
+            DELIVERED: "DELIVERED";
+            COMPLETED: "COMPLETED";
+            FAILED: "FAILED";
+        }>>;
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<{
+            HUMAN_AGENT: "HUMAN_AGENT";
+            CUSTOMER: "CUSTOMER";
+            AI_AGENT: "AI_AGENT";
+            AGENT: "AGENT";
+        }>>;
+        profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TACCommunication = z.infer<typeof TACCommunicationSchema>;
+
+/**
+ * Unified response wrapper for TAC.retrieveMemory().
+ *
+ * Provides a consistent interface for accessing memory data regardless of whether
+ * Memory API is configured or falling back to Conversation Orchestrator Communications API.
+ *
+ * Memory configured:
+ * - observations, summaries, communications all populated
+ * - communications include Memory-specific fields (author id, name, type, profileId)
+ *
+ * Conversation Orchestrator fallback:
+ * - observations and summaries are empty arrays
+ * - communications include Conversation Orchestrator-specific fields (conversationId, accountId, etc.)
+ */
+declare class TACMemoryResponse {
+    private readonly _data;
+    private readonly _communications;
+    /**
+     * Initialize wrapper with either Memory or Conversation Orchestrator data.
+     *
+     * @param data - Either MemoryRetrievalResponse (Memory) or Communication[] (Conversation Orchestrator)
+     */
+    constructor(data: MemoryRetrievalResponse | Communication[]);
+    /**
+     * Get observation memories.
+     *
+     * @returns List of observations if Memory is configured, empty array for Conversation Orchestrator fallback
+     */
+    get observations(): ObservationInfo[];
+    /**
+     * Get summary memories.
+     *
+     * @returns List of summaries if Memory is configured, empty array for Conversation Orchestrator fallback
+     */
+    get summaries(): SummaryInfo[];
+    /**
+     * Get communications in unified format with all available fields.
+     *
+     * Communications are converted to a common format during initialization that includes
+     * all fields from both Memory and Conversation Orchestrator APIs. Fields not available from a particular
+     * API will be undefined.
+     *
+     * @returns List of unified communications with all available fields
+     */
+    get communications(): TACCommunication[];
+    /**
+     * Check if Memory API is configured and providing full features.
+     *
+     * @returns true if Memory is configured (observations/summaries available),
+     *          false if using Conversation Orchestrator fallback (only communications available)
+     */
+    get hasMemoryFeatures(): boolean;
+    /**
+     * Access raw underlying data for advanced use cases.
+     *
+     * Use this when you need access to all fields from the original API responses,
+     * not just the unified common fields.
+     *
+     * @returns Either MemoryRetrievalResponse or Communication[] depending on configuration
+     */
+    get rawData(): MemoryRetrievalResponse | Communication[];
+    /**
+     * Build formatted prompt sections from available memory data.
+     *
+     * Generates markdown-formatted sections for observations, summaries, and communications
+     * that can be injected into LLM prompts. Each section includes a heading and formatted content.
+     * Sections with no data are omitted from the result.
+     *
+     * @returns Array of formatted prompt sections, empty array if no memory data available
+     */
+    buildMemoryPrompts(): string[];
+    private buildObservationsPrompt;
+    private buildSummariesPrompt;
+    private buildCommunicationsPrompt;
+}
+
 /**
  * Participant address type for different communication channels
  */
@@ -905,6 +1176,7 @@ declare const ConversationSessionSchema: z.ZodObject<{
         type: z.ZodDefault<z.ZodLiteral<"end">>;
         handoffData: z.ZodString;
     }, z.core.$strip>>;
+    cachedMemory: z.ZodOptional<z.ZodCustom<TACMemoryResponse, TACMemoryResponse>>;
 }, z.core.$strip>;
 type ConversationSession = z.infer<typeof ConversationSessionSchema>;
 /**
@@ -1386,6 +1658,135 @@ interface ConversationRelayConfig extends ConversationRelayAttributes {
     languages?: LanguageAttributes[] | undefined;
 }
 declare const ConversationRelayConfigSchema: z.ZodType<ConversationRelayConfig>;
+/**
+ * Twilio uses the same four-value enum for several attributes that control
+ * what caller input (DTMF, speech, both, neither) triggers a given behavior.
+ */
+declare const InterruptModeSchema: z.ZodEnum<{
+    any: "any";
+    speech: "speech";
+    none: "none";
+    dtmf: "dtmf";
+}>;
+type InterruptMode = z.infer<typeof InterruptModeSchema>;
+/**
+ * A single `<Language>` child for multi-language ConversationRelay setups.
+ *
+ * Maps to the `<Language>` element documented at
+ * https://www.twilio.com/docs/voice/twiml/connect/conversationrelay#language-element
+ *
+ * Distinct from {@link LanguageAttributes} (the Twilio-SDK-shaped type used by
+ * `connectConversationRelay`): this is the customization-facing model used in
+ * {@link TwiMLOptions}, mirroring the Python SDK's `LanguageConfig`.
+ */
+declare const LanguageConfigSchema: z.ZodObject<{
+    code: z.ZodString;
+    voice: z.ZodOptional<z.ZodString>;
+    ttsProvider: z.ZodOptional<z.ZodString>;
+    transcriptionProvider: z.ZodOptional<z.ZodString>;
+    speechModel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LanguageConfig = z.infer<typeof LanguageConfigSchema>;
+/**
+ * Options for the TwiML inside `<ConversationRelay>` (plus the
+ * `<Connect action>` URL).
+ *
+ * Fields map to the attributes documented at
+ * https://www.twilio.com/docs/voice/twiml/connect/conversationrelay . All
+ * fields are optional. `VoiceChannel.handleIncomingCall` merges these values
+ * over TAC defaults per-field — only fields explicitly present on the object
+ * override lower layers (see `VoiceChannel`'s overlay logic).
+ *
+ * This is the customization-facing counterpart to {@link ConversationRelayConfig}
+ * (which is the Twilio-SDK-shaped emit model and carries the required `url`).
+ * Mirrors the Python SDK's `TwiMLOptions`.
+ */
+declare const TwiMLOptionsSchema: z.ZodObject<{
+    customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    welcomeGreeting: z.ZodOptional<z.ZodString>;
+    welcomeGreetingInterruptible: z.ZodOptional<z.ZodEnum<{
+        any: "any";
+        speech: "speech";
+        none: "none";
+        dtmf: "dtmf";
+    }>>;
+    actionUrl: z.ZodOptional<z.ZodString>;
+    conversationConfiguration: z.ZodOptional<z.ZodString>;
+    websocketUrl: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    ttsLanguage: z.ZodOptional<z.ZodString>;
+    transcriptionLanguage: z.ZodOptional<z.ZodString>;
+    voice: z.ZodOptional<z.ZodString>;
+    ttsProvider: z.ZodOptional<z.ZodString>;
+    transcriptionProvider: z.ZodOptional<z.ZodString>;
+    speechModel: z.ZodOptional<z.ZodString>;
+    elevenlabsTextNormalization: z.ZodOptional<z.ZodEnum<{
+        on: "on";
+        auto: "auto";
+        off: "off";
+    }>>;
+    eotThreshold: z.ZodOptional<z.ZodNumber>;
+    partialPrompts: z.ZodOptional<z.ZodBoolean>;
+    deepgramSmartFormat: z.ZodOptional<z.ZodBoolean>;
+    speechTimeout: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>>;
+    interruptible: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        any: "any";
+        speech: "speech";
+        none: "none";
+        dtmf: "dtmf";
+    }>, z.ZodBoolean]>>;
+    interruptSensitivity: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    reportInputDuringAgentSpeech: z.ZodOptional<z.ZodEnum<{
+        any: "any";
+        speech: "speech";
+        none: "none";
+        dtmf: "dtmf";
+    }>>;
+    ignoreBackchannel: z.ZodOptional<z.ZodBoolean>;
+    preemptible: z.ZodOptional<z.ZodBoolean>;
+    dtmfDetection: z.ZodOptional<z.ZodBoolean>;
+    hints: z.ZodOptional<z.ZodString>;
+    events: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodString>;
+    intelligenceService: z.ZodOptional<z.ZodString>;
+    languages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        voice: z.ZodOptional<z.ZodString>;
+        ttsProvider: z.ZodOptional<z.ZodString>;
+        transcriptionProvider: z.ZodOptional<z.ZodString>;
+        speechModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>>;
+}, z.core.$strict>;
+type TwiMLOptions = z.infer<typeof TwiMLOptionsSchema>;
+/**
+ * Framework-neutral view of the Twilio TwiML webhook form.
+ *
+ * Populated by `TACServer` from the incoming Twilio webhook, then passed to a
+ * customizer registered via `VoiceChannel.onInboundCallTwiml(...)` so the
+ * application can produce per-call {@link TwiMLOptions} overrides without
+ * depending on Fastify types. Mirrors the Python SDK's `TwiMLRequest`.
+ */
+declare const TwiMLRequestSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    callSid: z.ZodOptional<z.ZodString>;
+    callerCountry: z.ZodOptional<z.ZodString>;
+    callerState: z.ZodOptional<z.ZodString>;
+    callerCity: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodString>;
+    extra: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+type TwiMLRequest = z.infer<typeof TwiMLRequestSchema>;
+/**
+ * Build a {@link TwiMLRequest} from a raw Twilio form dict, bucketing unknown
+ * keys into `extra`. Mirrors the Python SDK's `TwiMLRequest.from_form`.
+ */
+declare function twiMLRequestFromForm(form: Record<string, string>): TwiMLRequest;
 /**
  * ConversationRelay callback payload from Twilio webhook
  *
@@ -1431,11 +1832,32 @@ type ConversationRelayCallbackPayload = z.infer<typeof ConversationRelayCallback
  *
  * The caller identity is always TAC's configured `config.phoneNumber`.
  * Multi-number deployments should run one TAC instance per line.
+ *
+ * TwiML for the outbound call is built by merging per-field, highest precedence
+ * first:
+ *   1. This call's `twimlOptions` (per-call overrides)
+ *   2. `VoiceChannelConfig.defaultTwimlOptions` (channel-wide defaults)
+ *   3. TAC defaults (welcome greeting, conversationConfiguration, actionUrl
+ *      resolved via Studio handoff if configured, else derived from
+ *      `TACConfig.voicePublicDomain` + `voiceActionPath`)
+ *
+ * Fields you don't set at a layer fall through to lower layers — so
+ * `twimlOptions: { voice: 'es-MX-Neural2-A' }` on this call overrides only
+ * `voice`; `language`, `interruptible`, etc. from the channel config still apply.
  */
 interface InitiateVoiceConversationOptions {
     to: string;
-    conversationRelayConfig: ConversationRelayConfig;
-    actionUrl?: string | undefined;
+    /**
+     * Public WebSocket URL for ConversationRelay (e.g. 'wss://your-domain.ngrok.app/ws').
+     * Optional — defaults to the URL derived from `TACConfig.voicePublicDomain` +
+     * `voiceWebsocketPath`. Pass it here only to override the URL for a specific call.
+     */
+    websocketUrl?: string | undefined;
+    /**
+     * Per-call overrides for the TwiML inside `<ConversationRelay>`. Merged over
+     * `VoiceChannelConfig.defaultTwimlOptions` and TAC defaults.
+     */
+    twimlOptions?: TwiMLOptions | undefined;
 }
 declare const InitiateVoiceConversationOptionsSchema: z.ZodType<InitiateVoiceConversationOptions>;
 
@@ -1613,248 +2035,63 @@ type IntelligenceConfiguration = z.infer<typeof IntelligenceConfigurationSchema>
  */
 declare const OperatorResultEventSchema: z.ZodObject<{
     accountId: z.ZodString;
-    conversationId: z.ZodString;
-    memoryStoreId: z.ZodOptional<z.ZodString>;
-    intelligenceConfiguration: z.ZodObject<{
-        id: z.ZodString;
-        friendlyName: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    operatorResults: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        operator: z.ZodObject<{
-            id: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
-        outputFormat: z.ZodString;
-        result: z.ZodUnknown;
-        dateCreated: z.ZodString;
-        referenceIds: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
-        executionDetails: z.ZodOptional<z.ZodObject<{
-            participants: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                type: z.ZodString;
-                profileId: z.ZodOptional<z.ZodString>;
-                mediaParticipantId: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type OperatorResultEvent = z.infer<typeof OperatorResultEventSchema>;
-/**
- * Result of processing an operator result event
- */
-declare const OperatorProcessingResultSchema: z.ZodObject<{
-    success: z.ZodBoolean;
-    eventType: z.ZodOptional<z.ZodString>;
-    skipped: z.ZodDefault<z.ZodBoolean>;
-    skipReason: z.ZodOptional<z.ZodString>;
-    error: z.ZodOptional<z.ZodString>;
-    createdCount: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
-type OperatorProcessingResult = z.infer<typeof OperatorProcessingResultSchema>;
-/**
- * Conversation Intelligence configuration for TAC
- */
-declare const ConversationIntelligenceConfigSchema: z.ZodObject<{
-    configurationId: z.ZodString;
-    observationOperatorSid: z.ZodOptional<z.ZodString>;
-    summaryOperatorSid: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type ConversationIntelligenceConfig = z.infer<typeof ConversationIntelligenceConfigSchema>;
-/**
- * Summary item for batch creation
- */
-declare const ConversationSummaryItemSchema: z.ZodObject<{
-    content: z.ZodString;
-    conversationId: z.ZodString;
-    occurredAt: z.ZodString;
-    source: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type ConversationSummaryItem = z.infer<typeof ConversationSummaryItemSchema>;
-
-/**
- * Channel type for communications
- */
-declare const TACChannelTypeSchema: z.ZodEnum<{
-    VOICE: "VOICE";
-    SMS: "SMS";
-    RCS: "RCS";
-    EMAIL: "EMAIL";
-    WHATSAPP: "WHATSAPP";
-    CHAT: "CHAT";
-    API: "API";
-    SYSTEM: "SYSTEM";
-}>;
-type TACChannelType = z.infer<typeof TACChannelTypeSchema>;
-/**
- * Delivery status for communications
- */
-declare const TACDeliveryStatusSchema: z.ZodEnum<{
-    INITIATED: "INITIATED";
-    IN_PROGRESS: "IN_PROGRESS";
-    DELIVERED: "DELIVERED";
-    COMPLETED: "COMPLETED";
-    FAILED: "FAILED";
-}>;
-type TACDeliveryStatus = z.infer<typeof TACDeliveryStatusSchema>;
-/**
- * Participant type
- */
-declare const TACParticipantTypeSchema: z.ZodEnum<{
-    HUMAN_AGENT: "HUMAN_AGENT";
-    CUSTOMER: "CUSTOMER";
-    AI_AGENT: "AI_AGENT";
-    AGENT: "AGENT";
-}>;
-type TACParticipantType = z.infer<typeof TACParticipantTypeSchema>;
-/**
- * Unified author model with all fields from both Memory and Conversation Orchestrator APIs.
- *
- * Fields not available from a particular API will be undefined.
- */
-declare const TACCommunicationAuthorSchema: z.ZodObject<{
-    address: z.ZodString;
-    channel: z.ZodEnum<{
-        VOICE: "VOICE";
-        SMS: "SMS";
-        RCS: "RCS";
-        EMAIL: "EMAIL";
-        WHATSAPP: "WHATSAPP";
-        CHAT: "CHAT";
-        API: "API";
-        SYSTEM: "SYSTEM";
-    }>;
-    participantId: z.ZodOptional<z.ZodString>;
-    deliveryStatus: z.ZodOptional<z.ZodEnum<{
-        INITIATED: "INITIATED";
-        IN_PROGRESS: "IN_PROGRESS";
-        DELIVERED: "DELIVERED";
-        COMPLETED: "COMPLETED";
-        FAILED: "FAILED";
-    }>>;
-    id: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
-    type: z.ZodOptional<z.ZodEnum<{
-        HUMAN_AGENT: "HUMAN_AGENT";
-        CUSTOMER: "CUSTOMER";
-        AI_AGENT: "AI_AGENT";
-        AGENT: "AGENT";
-    }>>;
-    profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-type TACCommunicationAuthor = z.infer<typeof TACCommunicationAuthorSchema>;
-/**
- * Unified content model with all fields from both Memory and Conversation Orchestrator APIs.
- */
-declare const TACCommunicationContentSchema: z.ZodObject<{
-    type: z.ZodOptional<z.ZodEnum<{
-        TEXT: "TEXT";
-        TRANSCRIPTION: "TRANSCRIPTION";
-    }>>;
-    text: z.ZodOptional<z.ZodString>;
-    transcription: z.ZodOptional<z.ZodObject<{
-        channel: z.ZodOptional<z.ZodNumber>;
-        confidence: z.ZodOptional<z.ZodNumber>;
-        engine: z.ZodOptional<z.ZodString>;
-        words: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            text: z.ZodString;
-            startTime: z.ZodOptional<z.ZodString>;
-            endTime: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type TACCommunicationContent = z.infer<typeof TACCommunicationContentSchema>;
-/**
- * Unified communication model with all fields from both Memory and Conversation Orchestrator APIs.
- *
- * Provides complete access to all communication fields regardless of the source.
- * Fields not available from a particular API will be undefined.
- */
-declare const TACCommunicationSchema: z.ZodObject<{
-    id: z.ZodString;
-    author: z.ZodObject<{
-        address: z.ZodString;
-        channel: z.ZodEnum<{
-            VOICE: "VOICE";
-            SMS: "SMS";
-            RCS: "RCS";
-            EMAIL: "EMAIL";
-            WHATSAPP: "WHATSAPP";
-            CHAT: "CHAT";
-            API: "API";
-            SYSTEM: "SYSTEM";
-        }>;
-        participantId: z.ZodOptional<z.ZodString>;
-        deliveryStatus: z.ZodOptional<z.ZodEnum<{
-            INITIATED: "INITIATED";
-            IN_PROGRESS: "IN_PROGRESS";
-            DELIVERED: "DELIVERED";
-            COMPLETED: "COMPLETED";
-            FAILED: "FAILED";
-        }>>;
-        id: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
-        type: z.ZodOptional<z.ZodEnum<{
-            HUMAN_AGENT: "HUMAN_AGENT";
-            CUSTOMER: "CUSTOMER";
-            AI_AGENT: "AI_AGENT";
-            AGENT: "AGENT";
-        }>>;
-        profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    conversationId: z.ZodString;
+    memoryStoreId: z.ZodOptional<z.ZodString>;
+    intelligenceConfiguration: z.ZodObject<{
+        id: z.ZodString;
+        friendlyName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    content: z.ZodObject<{
-        type: z.ZodOptional<z.ZodEnum<{
-            TEXT: "TEXT";
-            TRANSCRIPTION: "TRANSCRIPTION";
-        }>>;
-        text: z.ZodOptional<z.ZodString>;
-        transcription: z.ZodOptional<z.ZodObject<{
-            channel: z.ZodOptional<z.ZodNumber>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            engine: z.ZodOptional<z.ZodString>;
-            words: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                text: z.ZodString;
-                startTime: z.ZodOptional<z.ZodString>;
-                endTime: z.ZodOptional<z.ZodString>;
+    operatorResults: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operator: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        outputFormat: z.ZodString;
+        result: z.ZodUnknown;
+        dateCreated: z.ZodString;
+        referenceIds: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        executionDetails: z.ZodOptional<z.ZodObject<{
+            participants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                profileId: z.ZodOptional<z.ZodString>;
+                mediaParticipantId: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>;
-    recipients: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        address: z.ZodString;
-        channel: z.ZodEnum<{
-            VOICE: "VOICE";
-            SMS: "SMS";
-            RCS: "RCS";
-            EMAIL: "EMAIL";
-            WHATSAPP: "WHATSAPP";
-            CHAT: "CHAT";
-            API: "API";
-            SYSTEM: "SYSTEM";
-        }>;
-        participantId: z.ZodOptional<z.ZodString>;
-        deliveryStatus: z.ZodOptional<z.ZodEnum<{
-            INITIATED: "INITIATED";
-            IN_PROGRESS: "IN_PROGRESS";
-            DELIVERED: "DELIVERED";
-            COMPLETED: "COMPLETED";
-            FAILED: "FAILED";
-        }>>;
-        id: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
-        type: z.ZodOptional<z.ZodEnum<{
-            HUMAN_AGENT: "HUMAN_AGENT";
-            CUSTOMER: "CUSTOMER";
-            AI_AGENT: "AI_AGENT";
-            AGENT: "AGENT";
-        }>>;
-        profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strip>>>;
-    channelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    createdAt: z.ZodOptional<z.ZodString>;
-    updatedAt: z.ZodOptional<z.ZodString>;
-    conversationId: z.ZodOptional<z.ZodString>;
-    accountId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
-type TACCommunication = z.infer<typeof TACCommunicationSchema>;
+type OperatorResultEvent = z.infer<typeof OperatorResultEventSchema>;
+/**
+ * Result of processing an operator result event
+ */
+declare const OperatorProcessingResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    eventType: z.ZodOptional<z.ZodString>;
+    skipped: z.ZodDefault<z.ZodBoolean>;
+    skipReason: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    createdCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type OperatorProcessingResult = z.infer<typeof OperatorProcessingResultSchema>;
+/**
+ * Conversation Intelligence configuration for TAC
+ */
+declare const ConversationIntelligenceConfigSchema: z.ZodObject<{
+    configurationId: z.ZodString;
+    observationOperatorSid: z.ZodOptional<z.ZodString>;
+    summaryOperatorSid: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ConversationIntelligenceConfig = z.infer<typeof ConversationIntelligenceConfigSchema>;
+/**
+ * Summary item for batch creation
+ */
+declare const ConversationSummaryItemSchema: z.ZodObject<{
+    content: z.ZodString;
+    conversationId: z.ZodString;
+    occurredAt: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ConversationSummaryItem = z.infer<typeof ConversationSummaryItemSchema>;
 
 /**
  * Knowledge base status enum
@@ -1909,82 +2146,6 @@ declare const KnowledgeSearchResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type KnowledgeSearchResponse = z.infer<typeof KnowledgeSearchResponseSchema>;
 
-/**
- * Unified response wrapper for TAC.retrieveMemory().
- *
- * Provides a consistent interface for accessing memory data regardless of whether
- * Memory API is configured or falling back to Conversation Orchestrator Communications API.
- *
- * Memory configured:
- * - observations, summaries, communications all populated
- * - communications include Memory-specific fields (author id, name, type, profileId)
- *
- * Conversation Orchestrator fallback:
- * - observations and summaries are empty arrays
- * - communications include Conversation Orchestrator-specific fields (conversationId, accountId, etc.)
- */
-declare class TACMemoryResponse {
-    private readonly _data;
-    private readonly _communications;
-    /**
-     * Initialize wrapper with either Memory or Conversation Orchestrator data.
-     *
-     * @param data - Either MemoryRetrievalResponse (Memory) or Communication[] (Conversation Orchestrator)
-     */
-    constructor(data: MemoryRetrievalResponse | Communication[]);
-    /**
-     * Get observation memories.
-     *
-     * @returns List of observations if Memory is configured, empty array for Conversation Orchestrator fallback
-     */
-    get observations(): ObservationInfo[];
-    /**
-     * Get summary memories.
-     *
-     * @returns List of summaries if Memory is configured, empty array for Conversation Orchestrator fallback
-     */
-    get summaries(): SummaryInfo[];
-    /**
-     * Get communications in unified format with all available fields.
-     *
-     * Communications are converted to a common format during initialization that includes
-     * all fields from both Memory and Conversation Orchestrator APIs. Fields not available from a particular
-     * API will be undefined.
-     *
-     * @returns List of unified communications with all available fields
-     */
-    get communications(): TACCommunication[];
-    /**
-     * Check if Memory API is configured and providing full features.
-     *
-     * @returns true if Memory is configured (observations/summaries available),
-     *          false if using Conversation Orchestrator fallback (only communications available)
-     */
-    get hasMemoryFeatures(): boolean;
-    /**
-     * Access raw underlying data for advanced use cases.
-     *
-     * Use this when you need access to all fields from the original API responses,
-     * not just the unified common fields.
-     *
-     * @returns Either MemoryRetrievalResponse or Communication[] depending on configuration
-     */
-    get rawData(): MemoryRetrievalResponse | Communication[];
-    /**
-     * Build formatted prompt sections from available memory data.
-     *
-     * Generates markdown-formatted sections for observations, summaries, and communications
-     * that can be injected into LLM prompts. Each section includes a heading and formatted content.
-     * Sections with no data are omitted from the result.
-     *
-     * @returns Array of formatted prompt sections, empty array if no memory data available
-     */
-    buildMemoryPrompts(): string[];
-    private buildObservationsPrompt;
-    private buildSummariesPrompt;
-    private buildCommunicationsPrompt;
-}
-
 /**
  * TAC Configuration class with Python-like static factory methods
  *
@@ -2011,6 +2172,10 @@ declare class TACConfig {
     readonly memoryConfig: TACConfigData['memoryConfig'];
     readonly conversationConfigurationId?: string;
     readonly voicePublicDomain?: string;
+    /** Path the voice WebSocket is served at (default '/ws'). */
+    readonly voiceWebsocketPath: string;
+    /** Path the ConversationRelay action callback is served at (default '/conversation-relay-callback'). */
+    readonly voiceActionPath: string;
     readonly cintelConfigurationId?: string;
     readonly cintelObservationOperatorSid?: string;
     readonly cintelSummaryOperatorSid?: string;
@@ -2038,7 +2203,9 @@ declare class TACConfig {
      * Optional environment variables:
      * - TWILIO_WHATSAPP_NUMBER: WhatsApp number for WhatsApp channel (e.g., 'whatsapp:+1234567890')
      * - TWILIO_CONVERSATION_CONFIGURATION_ID: Conversation Orchestrator configuration ID (enables orchestrated mode)
-     * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice WebSocket connections (domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
+     * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice routes (required for voice; domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
+     * - TWILIO_VOICE_WEBSOCKET_PATH: Path for the voice WebSocket (default: /ws)
+     * - TWILIO_VOICE_ACTION_PATH: Path for the ConversationRelay action callback (default: /conversation-relay-callback)
      * - TWILIO_REGION: Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`)
      * - TWILIO_STUDIO_HANDOFF_FLOW_SID: Studio Flow SID used by createStudioHandoffTool for human handoff
      * - TWILIO_RCS_SENDER_ID: RCS Sender ID for the RCS channel
@@ -2372,7 +2539,8 @@ interface BaseChannelOptions {
      * Memory retrieval mode for this channel. Default is "never".
      *
      * - "never": Memory is not automatically retrieved. Use the memory TAC tool or manually call `tac.retrieveMemory()` in callbacks for conditional retrieval.
-     * - "always": Memory is automatically retrieved for every inbound message and available in `onMessageReady` callback.
+     * - "always": Memory is automatically retrieved (using the message as query) for every inbound message and available in `onMessageReady` callback.
+     * - "once": Memory is retrieved once at conversation start with an empty query and cached on the session. Subsequent messages reuse the cache until the conversation becomes INACTIVE.
      */
     memoryMode?: MemoryMode;
     /**
@@ -2470,21 +2638,62 @@ declare abstract class BaseChannel {
      */
     protected validateWebhookPayload(payload: unknown): boolean;
     /**
-     * Extract conversation ID from webhook payload (implemented by subclasses)
+     * Preprocess webhook before handling event-specific logic.
+     * Handles deduplication, validation, filtering, and data extraction.
+     *
+     * @param payload - Raw webhook payload from Twilio
+     * @param idempotencyToken - Optional idempotency token for deduplication
+     * @returns Preprocessed webhook data, or null if webhook should be skipped
+     */
+    protected preprocessWebhook(payload: unknown, idempotencyToken: string | undefined): {
+        webhookData: ConversationWebhookPayload;
+        eventType: string;
+        conversationId: string | undefined;
+    } | null;
+    /**
+     * Extract conversation ID from webhook payload with type validation.
+     *
+     * Extracts conversationId from webhookData.data?.conversationId || webhookData.data?.id,
+     * validates the value is a non-empty string, and ensures it passes isConversationId check.
+     *
+     * This prevents invalid IDs from causing downstream issues like incorrect Map key
+     * matching in CONVERSATION_UPDATED self-filtering or propagating malformed IDs.
      */
-    protected abstract extractConversationId(payload: unknown): ConversationId | null;
+    protected extractConversationId(payload: unknown): ConversationId | null;
     /**
-     * Extract profile ID from webhook payload (implemented by subclasses)
+     * Extract profile ID from webhook payload with type validation.
+     *
+     * Extracts profileId from webhookData.data?.profileId,
+     * validates the value is a non-empty string, and ensures it passes isProfileId check.
+     *
+     * This prevents invalid IDs from propagating downstream and ensures consistent
+     * validation across all channel types.
      */
-    protected abstract extractProfileId(payload: unknown): ProfileId | null;
+    protected extractProfileId(payload: unknown): ProfileId | null;
     /**
-     * Retrieve memory only when memoryMode === 'always'.
+     * Retrieve memory according to the channel's memoryMode.
      *
      * This method handles the common logic for memory retrieval across all channels,
-     * including error handling and debug logging. If memoryMode is 'never',
-     * automatic memory retrieval is skipped.
+     * including error handling and debug logging.
+     *
+     * Modes:
+     * - "always": Fetch with the provided query on every message.
+     * - "once": Fetch once with an empty query and cache the result on the
+     *   session. Subsequent calls reuse the cache until it is invalidated on the
+     *   INACTIVE transition.
+     * - "never": Skip retrieval.
+     *
+     * Memory retrieval failures are logged and swallowed so message processing
+     * continues without memory context.
      */
     protected retrieveMemoryIfEnabled(session: ConversationSession, query?: string): Promise<TACMemoryResponse | undefined>;
+    /**
+     * Invalidate cached memory for "once" mode when a conversation becomes
+     * INACTIVE. Conversation Orchestrator updates memory on the INACTIVE
+     * transition, so the next message re-fetches fresh memory. No-op for other
+     * memory modes.
+     */
+    protected invalidateCachedMemory(conversationId: ConversationId): void;
     /**
      * Cleanup resources when shutting down
      */
@@ -2727,14 +2936,6 @@ declare abstract class MessagingChannel extends BaseChannel {
      * Handle conversation updated event
      */
     private handleConversationUpdated;
-    /**
-     * Extract conversation ID from webhook payload
-     */
-    protected extractConversationId(payload: unknown): ConversationId | null;
-    /**
-     * Extract profile ID from webhook payload
-     */
-    protected extractProfileId(payload: unknown): ProfileId | null;
     /**
      * Validate messaging channel webhook payload structure
      */
@@ -2976,6 +3177,34 @@ declare class ChatChannel extends MessagingChannel {
     initiateOutboundConversation(options: InitiateChatConversationOptions): Promise<InitiateConversationResult>;
 }
 
+/**
+ * Configuration for the Voice channel.
+ *
+ * `defaultTwimlOptions` is one of several TwiML layers that merge per-field;
+ * see `handleIncomingCall` (inbound) and `initiateOutboundConversation`
+ * (outbound) for the full precedence order.
+ */
+interface VoiceChannelConfig extends BaseChannelOptions {
+    /**
+     * Static `TwiMLOptions` applied to every call (inbound and outbound).
+     * Controls the TwiML inside `<ConversationRelay>` — voice, language,
+     * transcription provider, welcomeGreeting, `<Language>` children, etc. Use
+     * this when the same ConversationRelay configuration is correct for every call.
+     *
+     * Per-call inbound customization is registered via
+     * `VoiceChannel.onInboundCallTwiml(...)` (not on this config).
+     *
+     * Note: `customParameters` and `languages` replace wholesale when a
+     * higher-priority layer sets them.
+     */
+    defaultTwimlOptions?: TwiMLOptions;
+}
+/**
+ * Callback that produces per-call overrides for the TwiML inside
+ * `<ConversationRelay>` on inbound calls. Receives a framework-neutral
+ * {@link TwiMLRequest} and returns {@link TwiMLOptions}.
+ */
+type InboundCallTwimlHandler = (req: TwiMLRequest) => Promise<TwiMLOptions>;
 /**
  * Voice channel event callbacks extending base callbacks
  */
@@ -3024,7 +3253,45 @@ declare class VoiceChannel extends BaseChannel {
     private readonly callSidToConversationId;
     private readonly MAX_INITIALIZATION_RETRIES;
     private twilioClient;
-    constructor(tac: TAC, options?: BaseChannelOptions);
+    private readonly voiceConfig;
+    private onInboundCallTwimlHandler;
+    constructor(tac: TAC, options?: VoiceChannelConfig);
+    /**
+     * Register a callback that produces per-call overrides for the TwiML inside
+     * `<ConversationRelay>` on inbound calls.
+     *
+     * The callback receives a framework-neutral {@link TwiMLRequest} (parsed from
+     * the Twilio webhook form) and returns {@link TwiMLOptions}. Fields the
+     * callback explicitly sets override `defaultTwimlOptions` and TAC defaults;
+     * unset fields fall through.
+     *
+     * @example
+     * ```typescript
+     * voiceChannel.onInboundCallTwiml(async req => {
+     *   if (req.callerCountry === 'MX') {
+     *     return { language: 'es-MX', welcomeGreeting: '¡Hola!' };
+     *   }
+     *   return {};
+     * });
+     * ```
+     *
+     * Outbound calls don't use this — pass per-call TwiML via
+     * `InitiateVoiceConversationOptions.twimlOptions` directly.
+     */
+    onInboundCallTwiml(callback: InboundCallTwimlHandler): void;
+    /**
+     * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
+     * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
+     */
+    private resolveWebsocketUrl;
+    /**
+     * Resolve the default `<Connect action=...>` cleanup URL.
+     *
+     * Returns undefined if `voicePublicDomain` isn't set; that's fine because
+     * actionUrl has higher-priority layers (customizer, twimlOptions, Studio
+     * handoff) above this fallback.
+     */
+    private resolveDefaultActionUrl;
     private getTwilioClient;
     get channelType(): ChannelType;
     /**
@@ -3032,10 +3299,22 @@ declare class VoiceChannel extends BaseChannel {
      */
     on(event: string, callback: (...args: any[]) => void): void;
     /**
-     * Process webhook - Voice channel doesn't use traditional webhooks,
-     * but this method is required by the base class
+     * Process conversation webhooks for cleanup.
+     *
+     * Voice channel processes CONVERSATION_UPDATED events:
+     * - CLOSED status: Clean up local session state
+     *
+     * Note: Conversation tracking uses instance-local memory. In multi-instance
+     * deployments, webhooks may route to a different instance, preventing cleanup.
+     *
+     * @param payload - Raw webhook event data from Twilio
+     * @param idempotencyToken - Optional Twilio idempotency token from request headers
+     */
+    processWebhook(payload: unknown, idempotencyToken?: string): Promise<void>;
+    /**
+     * Handle conversation updated event
      */
-    processWebhook(_payload: unknown): Promise<void>;
+    private handleConversationUpdated;
     /**
      * Get active WebSocket connection for a conversation
      */
@@ -3053,7 +3332,9 @@ declare class VoiceChannel extends BaseChannel {
      */
     private handleInterruptMessage;
     /**
-     * Handle WebSocket disconnection
+     * Handle WebSocket disconnection. In orchestrated mode the conversation stays
+     * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
+     * voice-only mode there is no such webhook, so it ends here.
      */
     private handleWebSocketDisconnect;
     /**
@@ -3075,18 +3356,89 @@ declare class VoiceChannel extends BaseChannel {
         signal?: AbortSignal;
     }): Promise<string>;
     /**
-     * Handle incoming voice call - generate TwiML to connect to ConversationRelay
+     * Generate the TwiML response for an incoming voice call.
+     *
+     * ConversationRelay automatically handles conversation creation and
+     * participant management via the `conversationConfiguration` parameter.
+     *
+     * The WebSocket URL and default session-cleanup action URL are derived from
+     * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` /
+     * `voiceActionPath`.
+     *
+     * TwiML fields are merged per-field, highest precedence first:
+     *   1. Output of the customizer registered via
+     *      `VoiceChannel.onInboundCallTwiml(...)` if configured and `twimlRequest`
+     *      is given. (Application-owned.)
+     *   2. `VoiceChannelConfig.defaultTwimlOptions` — per-channel defaults.
+     *   3. `hostTwimlOptions` — per-call transport facts supplied by the host (the
+     *      code owning the route), e.g. a per-call `websocketUrl` with an affinity
+     *      token.
+     *   4. TAC defaults: a fixed default welcomeGreeting, `conversationConfiguration`
+     *      from `TACConfig`, `actionUrl` resolved via Studio handoff (when
+     *      `studioHandoffFlowSid` is configured), else derived from
+     *      `TACConfig.voicePublicDomain` + `voiceActionPath`, and the `websocketUrl`
+     *      derived from `TACConfig.voicePublicDomain` + `voiceWebsocketPath`.
+     *
+     * Fields not set at a layer fall through to lower layers. Arrays (`languages`)
+     * and nested objects (`customParameters`) replace wholesale when set at a
+     * higher-priority layer. `websocketUrl` falls back to the `TACConfig`-derived
+     * URL if unset at every layer.
+     *
+     * @param twimlRequest - Parsed Twilio webhook fields. Passed to the customizer
+     *   if one is configured on the channel.
+     * @param options - Additional per-call inputs.
+     * @param options.hostTwimlOptions - Per-call TwiML supplied by a custom
+     *   in-process host (e.g. an affinity-routed deployment injecting a per-call
+     *   `websocketUrl`), layered below `defaultTwimlOptions` and the application
+     *   customizer but above the TAC defaults.
+     * @returns TwiML XML string for call connection.
+     */
+    handleIncomingCall(twimlRequest?: TwiMLRequest, options?: {
+        hostTwimlOptions?: TwiMLOptions;
+    }): Promise<string>;
+    /**
+     * Layer TwiML options, lowest precedence first: TAC defaults → `host`
+     * (calling host's per-call values) → channel `defaultTwimlOptions` → `perCall`
+     * (application customizer output for inbound, or
+     * `InitiateVoiceConversationOptions.twimlOptions` for outbound).
+     */
+    private buildTwimlOptions;
+    /**
+     * Apply fields explicitly present on `source` onto `target`.
+     *
+     * Nested objects (`customParameters`), arrays (`languages`), and dicts
+     * (`extra`) replace wholesale — there's no per-key merging.
      *
-     * ConversationRelay will create the conversation automatically. The conversation
-     * will be initialized on the first prompt using the callSid.
+     * `actionUrl` is skipped here on purpose — it's resolved once via
+     * `resolveActionUrl` looking at every layer at once, and that resolved value
+     * is written into `target` before this overlay runs. Letting it through here
+     * would let a higher-priority layer that didn't set actionUrl silently clobber
+     * a lower layer that did.
      *
-     * @param options - Options for handling the incoming call
-     * @returns TwiML XML string with ConversationRelay configuration
+     * "Explicitly present" is detected via key presence (`key in source`), which
+     * mirrors Python's `model_fields_set`: a key set to `undefined` is still
+     * "present" and overrides lower layers, while an absent key falls through.
      */
-    handleIncomingCall(options: {
-        actionUrl?: string;
-        conversationRelayConfig: ConversationRelayConfig;
-    }): string;
+    private overlayFields;
+    /**
+     * Resolve the TwiML `<Connect action=...>` URL.
+     *
+     * Precedence (highest to lowest):
+     *   1. application customizer
+     *   2. channel `defaultTwimlOptions`
+     *   3. `host` (calling host's per-call options)
+     *   4. Studio handoff (when `studioHandoffFlowSid` is configured)
+     *   5. Channel default — derived from `TACConfig.voicePublicDomain` +
+     *      `TACConfig.voiceActionPath`.
+     *
+     * User-expressed intent (Studio handoff is configured explicitly on
+     * `TACConfig`) beats the SDK's generated cleanup default.
+     *
+     * Explicit `actionUrl: undefined` on a layer (key present, value undefined)
+     * suppresses `<Connect action=...>` entirely — all lower layers are skipped.
+     * `actionUrl` left absent (key not present) falls through to the next layer.
+     */
+    private resolveActionUrl;
     /**
      * Initiate an outbound voice conversation
      *
@@ -3095,14 +3447,21 @@ declare class VoiceChannel extends BaseChannel {
      * conversation during passive hydration. The session is initialized lazily
      * on the first prompt when the conversation is discovered by callSid.
      *
-     * `conversationRelayConfig.url` must be the publicly accessible WebSocket
-     * endpoint (e.g., `wss://your-domain.ngrok.app/ws`). Unlike inbound calls
-     * where TACServer sets this automatically, outbound calls require it
-     * explicitly since there is no incoming HTTP request to derive the host from.
+     * TwiML fields are merged per-field, highest precedence first:
+     *   1. `options.twimlOptions` — per-call overrides
+     *   2. `VoiceChannelConfig.defaultTwimlOptions` — channel-wide defaults
+     *   3. TAC defaults: welcome greeting, `conversationConfiguration` from
+     *      `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
+     *      derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
+     *
+     * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
+     * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
+     * `options.websocketUrl`.
      */
     initiateOutboundConversation(options: InitiateVoiceConversationOptions): Promise<InitiateVoiceConversationResult>;
     /**
-     * Handle ConversationRelay callback from Twilio
+     * Handle ConversationRelay callback from Twilio. Cleans up on call completion
+     * in voice-only mode; in orchestrated mode the CO webhook owns cleanup.
      *
      * @param payload - Callback payload from Twilio
      * @returns Response with status, content, and content type
@@ -3139,6 +3498,29 @@ declare class VoiceChannel extends BaseChannel {
      * @returns true if an active task exists
      */
     hasActiveStreamTask(conversationId: ConversationId): boolean;
+    /**
+     * Field names on {@link TwiMLOptions} that map directly to `<ConversationRelay>`
+     * attributes (camelCase, emitted as-is). Excludes the fields handled specially
+     * by {@link generateTwiml}: websocketUrl (resolved through the layered merge and
+     * emitted as the `url` attribute), actionUrl, languages, customParameters, extra.
+     */
+    private static readonly RELAY_ATTR_FIELDS;
+    /**
+     * Generate TwiML XML for ConversationRelay from a merged {@link TwiMLOptions}.
+     *
+     * This is the low-level emitter used by `handleIncomingCall` and
+     * `initiateOutboundConversation` after layering. It mirrors the Python SDK's
+     * `generate_twiml`. The WebSocket URL may be passed as `websocketUrl` or via
+     * `options.websocketUrl` (the explicit argument wins when both are given), so a
+     * channel-less caller can pass everything in one object.
+     *
+     * @param websocketUrl - Public WebSocket URL (e.g. 'wss://example.ngrok.app/ws').
+     *   Optional if `options.websocketUrl` is set.
+     * @param options - Merged TwiMLOptions to emit.
+     * @returns TwiML XML string ready to return to Twilio.
+     * @throws {Error} if no WebSocket URL is provided via either source.
+     */
+    private generateTwiml;
     /**
      * Generate TwiML to connect a call to ConversationRelay.
      * Validates configuration with Zod before generating TwiML.
@@ -3157,14 +3539,6 @@ declare class VoiceChannel extends BaseChannel {
      * Keeps null, false, 0, and empty strings as they are valid values.
      */
     private filterUnsetValues;
-    /**
-     * Extract conversation ID - Not applicable for Voice channel
-     */
-    protected extractConversationId(_payload: unknown): ConversationId | null;
-    /**
-     * Extract profile ID - Not applicable for Voice channel
-     */
-    protected extractProfileId(_payload: unknown): ProfileId | null;
     /**
      * Cleanup channel state on shutdown
      *
@@ -3617,17 +3991,23 @@ interface TACServerConfig {
     host?: string;
     /** Port to bind the server to (default: 8000) */
     port?: number;
-    /** Custom webhook paths */
+    /**
+     * Custom server-only webhook paths. The voice WebSocket and ConversationRelay
+     * action callback paths live on `TACConfig` (`voiceWebsocketPath` /
+     * `voiceActionPath`) because they're consumed by the voice channel regardless
+     * of which web framework is used; this server reads them from there.
+     */
     webhookPaths?: {
+        /**
+         * @deprecated Use `conversation` instead. This field will be removed in a future version.
+         * If both `messaging` and `conversation` are set, `conversation` takes precedence.
+         */
         messaging?: string;
+        conversation?: string;
         twiml?: string;
-        ws?: string;
-        conversationRelayCallback?: string;
         /** Path for Conversation Intelligence webhook (optional - only registered if provided) */
         cintel?: string;
     };
-    /** ConversationRelay configuration (welcomeGreeting, transcription, TTS, interaction settings, etc.) */
-    conversationRelayConfig?: Partial<Omit<ConversationRelayConfig, 'url'>>;
     /** Voice channel instance (alternative to registering on TAC) */
     voiceChannel?: VoiceChannel;
     /** Messaging channel instances — webhooks are fanned out to all (alternative to registering on TAC) */
@@ -3660,10 +4040,12 @@ declare class TACServer {
     readonly fastify: FastifyInstance;
     private readonly tac;
     private readonly config;
-    /** All enabled messaging channels — webhooks are fanned out to each one */
+    /** All enabled messaging channels */
     private readonly messagingChannels;
     /** Voice channel instance */
     private readonly voiceChannel;
+    /** All channels that need webhook processing (voice + messaging) */
+    private readonly webhookChannels;
     constructor(tac: TAC, config?: TACServerConfig);
     private getForwardedProto;
     private getForwardedHost;
@@ -3698,4 +4080,4 @@ declare class TACServer {
     stop(): Promise<void>;
 }
 
-export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, 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 CustomParameters, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, 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 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, 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 TwilioMemoryConfig, TwilioMemoryConfigSchema, VoiceChannel, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _SDKDriftGuards, buildHandoffPayload, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl };
+export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, 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 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 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, 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, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _SDKDriftGuards, buildHandoffPayload, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };