twilio-agent-connect 2.4.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -44,14 +44,17 @@ declare const CALL_EVENT_KINDS: readonly CallEventKind[];
44
44
  /**
45
45
  * TAC configuration schema
46
46
  */
47
- declare const TACConfigSchema: z.ZodObject<{
47
+ declare const TACConfigSchema: z.ZodPipe<z.ZodObject<{
48
48
  accountSid: z.ZodString;
49
49
  authToken: z.ZodString;
50
50
  apiKey: z.ZodString;
51
51
  apiSecret: z.ZodString;
52
- phoneNumber: z.ZodString;
52
+ phoneNumber: z.ZodOptional<z.ZodString>;
53
+ phoneNumbers: z.ZodOptional<z.ZodArray<z.ZodString>>;
53
54
  rcsSenderId: z.ZodOptional<z.ZodString>;
55
+ rcsSenderIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
54
56
  whatsappNumber: z.ZodOptional<z.ZodString>;
57
+ whatsappNumbers: z.ZodOptional<z.ZodArray<z.ZodString>>;
55
58
  memoryConfig: z.ZodPrefault<z.ZodObject<{
56
59
  traitGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
57
60
  observationsLimit: z.ZodDefault<z.ZodNumber>;
@@ -63,14 +66,85 @@ declare const TACConfigSchema: z.ZodObject<{
63
66
  }, z.core.$strip>>;
64
67
  conversationConfigurationId: z.ZodOptional<z.ZodString>;
65
68
  voicePublicDomain: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
66
- voiceWebsocketPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
67
- voiceActionPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
68
- voiceCallEventPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
69
+ instancePublicDomain: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
70
+ voiceWebsocketPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
71
+ voiceActionPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
72
+ voiceCallEventPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
69
73
  cintelConfigurationId: z.ZodOptional<z.ZodString>;
70
74
  cintelSummaryOperatorSid: z.ZodOptional<z.ZodString>;
71
75
  region: z.ZodOptional<z.ZodString>;
72
76
  studioHandoffFlowSid: z.ZodOptional<z.ZodString>;
73
- }, z.core.$strip>;
77
+ }, z.core.$strip>, z.ZodTransform<{
78
+ phoneNumber: string | undefined;
79
+ phoneNumbers: string[];
80
+ rcsSenderId: string | undefined;
81
+ rcsSenderIds: string[];
82
+ whatsappNumber: string | undefined;
83
+ whatsappNumbers: string[];
84
+ accountSid: string;
85
+ authToken: string;
86
+ apiKey: string;
87
+ apiSecret: string;
88
+ memoryConfig: {
89
+ observationsLimit: number;
90
+ summariesLimit: number;
91
+ communicationsLimit: number;
92
+ relevanceThreshold: number;
93
+ phoneTraitGroup: string;
94
+ phoneTraitField: string;
95
+ traitGroups?: string[] | undefined;
96
+ };
97
+ voiceWebsocketPath: string;
98
+ voiceActionPath: string;
99
+ voiceCallEventPath: string;
100
+ conversationConfigurationId?: string | undefined;
101
+ voicePublicDomain?: string | undefined;
102
+ instancePublicDomain?: string | undefined;
103
+ cintelConfigurationId?: string | undefined;
104
+ cintelSummaryOperatorSid?: string | undefined;
105
+ region?: string | undefined;
106
+ studioHandoffFlowSid?: string | undefined;
107
+ }, {
108
+ accountSid: string;
109
+ authToken: string;
110
+ apiKey: string;
111
+ apiSecret: string;
112
+ memoryConfig: {
113
+ observationsLimit: number;
114
+ summariesLimit: number;
115
+ communicationsLimit: number;
116
+ relevanceThreshold: number;
117
+ phoneTraitGroup: string;
118
+ phoneTraitField: string;
119
+ traitGroups?: string[] | undefined;
120
+ };
121
+ voiceWebsocketPath: string;
122
+ voiceActionPath: string;
123
+ voiceCallEventPath: string;
124
+ phoneNumber?: string | undefined;
125
+ phoneNumbers?: string[] | undefined;
126
+ rcsSenderId?: string | undefined;
127
+ rcsSenderIds?: string[] | undefined;
128
+ whatsappNumber?: string | undefined;
129
+ whatsappNumbers?: string[] | undefined;
130
+ conversationConfigurationId?: string | undefined;
131
+ voicePublicDomain?: string | undefined;
132
+ instancePublicDomain?: string | undefined;
133
+ cintelConfigurationId?: string | undefined;
134
+ cintelSummaryOperatorSid?: string | undefined;
135
+ region?: string | undefined;
136
+ studioHandoffFlowSid?: string | undefined;
137
+ }>>;
138
+ /**
139
+ * Raw TAC configuration accepted by `new TACConfig()` and `TACOptions.config`.
140
+ * Fields the schema back-fills or defaults (e.g. `phoneNumbers`, `memoryConfig`)
141
+ * are optional here.
142
+ */
143
+ type TACConfigInput = z.input<typeof TACConfigSchema>;
144
+ /**
145
+ * Normalized TAC configuration produced by validating a {@link TACConfigInput}:
146
+ * defaults applied and each sender pair back-filled (default first, de-duplicated).
147
+ */
74
148
  type TACConfigData = z.infer<typeof TACConfigSchema>;
75
149
  /**
76
150
  * Environment variable mapping for configuration
@@ -81,8 +155,11 @@ declare const EnvironmentVariables: {
81
155
  readonly TWILIO_API_KEY: "TWILIO_API_KEY";
82
156
  readonly TWILIO_API_SECRET: "TWILIO_API_SECRET";
83
157
  readonly TWILIO_PHONE_NUMBER: "TWILIO_PHONE_NUMBER";
158
+ readonly TWILIO_PHONE_NUMBERS: "TWILIO_PHONE_NUMBERS";
84
159
  readonly TWILIO_RCS_SENDER_ID: "TWILIO_RCS_SENDER_ID";
160
+ readonly TWILIO_RCS_SENDER_IDS: "TWILIO_RCS_SENDER_IDS";
85
161
  readonly TWILIO_WHATSAPP_NUMBER: "TWILIO_WHATSAPP_NUMBER";
162
+ readonly TWILIO_WHATSAPP_NUMBERS: "TWILIO_WHATSAPP_NUMBERS";
86
163
  readonly TWILIO_MEMORY_PROFILE_TRAIT_GROUPS: "TWILIO_MEMORY_PROFILE_TRAIT_GROUPS";
87
164
  readonly TWILIO_MEMORY_OBSERVATIONS_LIMIT: "TWILIO_MEMORY_OBSERVATIONS_LIMIT";
88
165
  readonly TWILIO_MEMORY_SUMMARIES_LIMIT: "TWILIO_MEMORY_SUMMARIES_LIMIT";
@@ -92,6 +169,7 @@ declare const EnvironmentVariables: {
92
169
  readonly TWILIO_MEMORY_PHONE_TRAIT_FIELD: "TWILIO_MEMORY_PHONE_TRAIT_FIELD";
93
170
  readonly TWILIO_CONVERSATION_CONFIGURATION_ID: "TWILIO_CONVERSATION_CONFIGURATION_ID";
94
171
  readonly TWILIO_VOICE_PUBLIC_DOMAIN: "TWILIO_VOICE_PUBLIC_DOMAIN";
172
+ readonly TWILIO_INSTANCE_PUBLIC_DOMAIN: "TWILIO_INSTANCE_PUBLIC_DOMAIN";
95
173
  readonly TWILIO_VOICE_WEBSOCKET_PATH: "TWILIO_VOICE_WEBSOCKET_PATH";
96
174
  readonly TWILIO_VOICE_ACTION_PATH: "TWILIO_VOICE_ACTION_PATH";
97
175
  readonly TWILIO_VOICE_CALL_EVENT_PATH: "TWILIO_VOICE_CALL_EVENT_PATH";
@@ -1253,6 +1331,7 @@ declare const ConversationResponseSchema: z.ZodObject<{
1253
1331
  configurationId: z.ZodOptional<z.ZodString>;
1254
1332
  createdAt: z.ZodOptional<z.ZodString>;
1255
1333
  updatedAt: z.ZodOptional<z.ZodString>;
1334
+ metadata: z.ZodPreprocess<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
1256
1335
  }, z.core.$strip>;
1257
1336
  type ConversationResponse = z.infer<typeof ConversationResponseSchema>;
1258
1337
  /**
@@ -1267,6 +1346,7 @@ declare const ListConversationsResponseSchema: z.ZodObject<{
1267
1346
  configurationId: z.ZodOptional<z.ZodString>;
1268
1347
  createdAt: z.ZodOptional<z.ZodString>;
1269
1348
  updatedAt: z.ZodOptional<z.ZodString>;
1349
+ metadata: z.ZodPreprocess<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
1270
1350
  }, z.core.$strip>>;
1271
1351
  }, z.core.$strip>;
1272
1352
  type ListConversationsResponse = z.infer<typeof ListConversationsResponseSchema>;
@@ -1463,16 +1543,18 @@ declare const ConversationConfigurationSchema: z.ZodObject<{
1463
1543
  }, z.core.$strip>;
1464
1544
  type ConversationConfiguration = z.infer<typeof ConversationConfigurationSchema>;
1465
1545
  /**
1466
- * Options for initiating an outbound SMS conversation.
1546
+ * Options for initiating an outbound messaging conversation (SMS/RCS/WhatsApp).
1467
1547
  *
1468
- * The sender is always TAC's configured `config.phoneNumber`. Multi-sender
1469
- * deployments should run one TAC instance per sender so inbound webhook
1470
- * routing, memory scoping, and configuration stay in sync.
1548
+ * The sender defaults to the channel's configured default (`config.phoneNumber`
1549
+ * for SMS, `config.rcsSenderId` for RCS, `config.whatsappNumber` for WhatsApp).
1550
+ * Set `from` to send from any other configured sender for that channel
1551
+ * (`config.phoneNumbers` / `rcsSenderIds` / `whatsappNumbers`).
1471
1552
  */
1472
1553
  declare const InitiateMessagingConversationOptionsSchema: z.ZodObject<{
1473
1554
  to: z.ZodString;
1474
1555
  message: z.ZodString;
1475
1556
  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1557
+ from: z.ZodOptional<z.ZodString>;
1476
1558
  }, z.core.$strip>;
1477
1559
  type InitiateMessagingConversationOptions = z.infer<typeof InitiateMessagingConversationOptionsSchema>;
1478
1560
  /**
@@ -2224,8 +2306,8 @@ declare function callOptionsToCreateParams(options: CallOptions): Record<string,
2224
2306
  /**
2225
2307
  * Options for initiating an outbound voice conversation.
2226
2308
  *
2227
- * The caller identity is always TAC's configured `config.phoneNumber`.
2228
- * Multi-number deployments should run one TAC instance per line.
2309
+ * The caller identity is TAC's configured `config.phoneNumber` by default, or
2310
+ * `from` when set to one of `config.phoneNumbers`.
2229
2311
  *
2230
2312
  * TwiML for the outbound call is built by merging per-field, highest precedence
2231
2313
  * first:
@@ -2241,6 +2323,11 @@ declare function callOptionsToCreateParams(options: CallOptions): Record<string,
2241
2323
  */
2242
2324
  interface InitiateVoiceConversationOptions {
2243
2325
  to: string;
2326
+ /**
2327
+ * Phone number to place the call from. Must be one of `config.phoneNumbers`.
2328
+ * When omitted, `config.phoneNumber` (the default sender) is used.
2329
+ */
2330
+ from?: string | undefined;
2244
2331
  /**
2245
2332
  * Public WebSocket URL for ConversationRelay (e.g. 'wss://your-domain.ngrok.app/ws').
2246
2333
  * Optional — defaults to the URL derived from `TACConfig.voicePublicDomain` +
@@ -2284,6 +2371,7 @@ declare const InitiateVoiceConversationOptionsSchema: z.ZodType<InitiateVoiceCon
2284
2371
  */
2285
2372
  declare const InitiateVoiceConversationOptionsOpenAIRealtimeSchema: z.ZodObject<{
2286
2373
  to: z.ZodString;
2374
+ from: z.ZodOptional<z.ZodString>;
2287
2375
  websocketUrl: z.ZodOptional<z.ZodURL>;
2288
2376
  callOptions: z.ZodOptional<z.ZodType<CallOptions, unknown, z.core.$ZodTypeInternals<CallOptions, unknown>>>;
2289
2377
  twimlOptions: z.ZodOptional<z.ZodObject<{
@@ -2313,6 +2401,7 @@ type InitiateVoiceConversationOptionsOpenAIRealtime = z.infer<typeof InitiateVoi
2313
2401
  */
2314
2402
  declare const InitiateVoiceConversationOptionsGPTLiveSchema: z.ZodObject<{
2315
2403
  to: z.ZodString;
2404
+ from: z.ZodOptional<z.ZodString>;
2316
2405
  websocketUrl: z.ZodOptional<z.ZodURL>;
2317
2406
  callOptions: z.ZodOptional<z.ZodType<CallOptions, unknown, z.core.$ZodTypeInternals<CallOptions, unknown>>>;
2318
2407
  twimlOptions: z.ZodOptional<z.ZodObject<{
@@ -2708,12 +2797,35 @@ declare class TACConfig {
2708
2797
  readonly authToken: string;
2709
2798
  readonly apiKey: string;
2710
2799
  readonly apiSecret: string;
2711
- readonly phoneNumber: string;
2800
+ /**
2801
+ * Default Twilio phone number for Voice and SMS — the sender used for
2802
+ * outbound when a call does not specify `from`. Undefined when no phone
2803
+ * number is configured (the Voice and SMS channels then refuse to
2804
+ * construct, and Studio handoff from Chat returns `handoff_failed`);
2805
+ * otherwise a member of {@link phoneNumbers}.
2806
+ */
2807
+ readonly phoneNumber?: string;
2808
+ /**
2809
+ * Full set of Twilio phone numbers this instance serves for Voice and SMS
2810
+ * (the inbound allowlist). Empty when none is configured; otherwise includes
2811
+ * {@link phoneNumber} as the first, default sender.
2812
+ */
2813
+ readonly phoneNumbers: string[];
2712
2814
  readonly rcsSenderId?: string;
2815
+ /** Full set of RCS Sender IDs this instance serves; the default is first. */
2816
+ readonly rcsSenderIds: string[];
2713
2817
  readonly whatsappNumber?: string;
2818
+ /** Full set of WhatsApp numbers this instance serves; the default is first. */
2819
+ readonly whatsappNumbers: string[];
2714
2820
  readonly memoryConfig: TACConfigData['memoryConfig'];
2715
2821
  readonly conversationConfigurationId?: string;
2716
2822
  readonly voicePublicDomain?: string;
2823
+ /**
2824
+ * This process's own directly-routable host. When set, the WebSocket and
2825
+ * action URLs (and call-event callbacks on calls TAC places) point here
2826
+ * instead of at {@link voicePublicDomain}. See {@link voiceCallbackDomain}.
2827
+ */
2828
+ readonly instancePublicDomain?: string;
2717
2829
  /** Path the voice WebSocket is served at (default '/ws'). */
2718
2830
  readonly voiceWebsocketPath: string;
2719
2831
  /** Path the ConversationRelay action callback is served at (default '/conversation-relay-callback'). */
@@ -2732,7 +2844,7 @@ declare class TACConfig {
2732
2844
  * from this SID.
2733
2845
  */
2734
2846
  readonly studioHandoffFlowSid?: string;
2735
- constructor(data: TACConfigData | z.input<typeof TACConfigSchema>);
2847
+ constructor(data: TACConfigInput);
2736
2848
  /**
2737
2849
  * Create TACConfig from environment variables.
2738
2850
  *
@@ -2741,18 +2853,33 @@ declare class TACConfig {
2741
2853
  * - TWILIO_AUTH_TOKEN: Twilio Auth Token for API authentication
2742
2854
  * - TWILIO_API_KEY: Twilio API Key SID (starts with SK)
2743
2855
  * - TWILIO_API_SECRET: Twilio API Secret for API Key authentication
2744
- * - TWILIO_PHONE_NUMBER: Phone number for voice and SMS channels
2745
2856
  *
2746
2857
  * Optional environment variables:
2747
- * - TWILIO_WHATSAPP_NUMBER: WhatsApp number for WhatsApp channel (e.g., 'whatsapp:+1234567890')
2858
+ * - TWILIO_PHONE_NUMBER / TWILIO_PHONE_NUMBERS: phone number(s) for the voice and SMS
2859
+ * channels, which require at least one — see **Multi-Value Senders** below.
2860
+ * - TWILIO_WHATSAPP_NUMBER / TWILIO_WHATSAPP_NUMBERS: WhatsApp number(s) for the
2861
+ * WhatsApp channel (e.g., 'whatsapp:+1234567890')
2862
+ * - TWILIO_RCS_SENDER_ID / TWILIO_RCS_SENDER_IDS: RCS Sender ID(s) for the RCS channel
2748
2863
  * - TWILIO_CONVERSATION_CONFIGURATION_ID: Conversation Orchestrator configuration ID (enables orchestrated mode)
2749
2864
  * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice routes (required for voice; a port and/or base path are allowed, e.g., 'abc123.ngrok.app', 'example.ngrok.app:8080', or 'example.com/server1')
2865
+ * - TWILIO_INSTANCE_PUBLIC_DOMAIN: This process's own directly-routable host, for pinning a
2866
+ * call's out-of-band webhooks to the instance holding its WebSocket (multi-replica voice only)
2750
2867
  * - TWILIO_VOICE_WEBSOCKET_PATH: Path for the voice WebSocket (default: /ws)
2751
2868
  * - TWILIO_VOICE_ACTION_PATH: Path for the ConversationRelay action callback (default: /conversation-relay-callback)
2752
2869
  * - TWILIO_VOICE_CALL_EVENT_PATH: Base path for the call-event callbacks — status, async AMD, recording (default: /twilio/call-events)
2753
2870
  * - TWILIO_REGION: Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`)
2754
2871
  * - TWILIO_STUDIO_HANDOFF_FLOW_SID: Studio Flow SID used by createStudioHandoffTool for human handoff
2755
- * - TWILIO_RCS_SENDER_ID: RCS Sender ID for the RCS channel
2872
+ *
2873
+ * Multi-Value Senders:
2874
+ * - Each singular env var (TWILIO_PHONE_NUMBER, TWILIO_RCS_SENDER_ID,
2875
+ * TWILIO_WHATSAPP_NUMBER) pairs with a plural, comma-separated one
2876
+ * (TWILIO_PHONE_NUMBERS, TWILIO_RCS_SENDER_IDS, TWILIO_WHATSAPP_NUMBERS),
2877
+ * e.g. `TWILIO_PHONE_NUMBERS=+1555,+1444`. Whichever side is set back-fills
2878
+ * the other: the singular becomes the default sender and the plural the full
2879
+ * allowlist. Entries are whitespace-trimmed and de-duplicated, with the
2880
+ * default kept first. All three pairs are optional at the config level; each
2881
+ * channel requires its own pair at construction (Voice and SMS need
2882
+ * `phoneNumber`/`phoneNumbers`).
2756
2883
  *
2757
2884
  * Memory Configuration (defaults defined in TwilioMemoryConfigSchema):
2758
2885
  * - TWILIO_MEMORY_PROFILE_TRAIT_GROUPS: Trait groups to include (comma-separated, e.g., "Contact,Preferences")
@@ -2782,6 +2909,11 @@ declare class TACConfig {
2782
2909
  * and TACServer registers routes at it, so the two can't drift.
2783
2910
  */
2784
2911
  callEventPath(kind: CallEventKind): string;
2912
+ /**
2913
+ * Host Twilio should reach for a call in progress: {@link instancePublicDomain}
2914
+ * if set, else the shared {@link voicePublicDomain}.
2915
+ */
2916
+ get voiceCallbackDomain(): string | undefined;
2785
2917
  /**
2786
2918
  * Public URL for a call-event callback, or `undefined` without a public domain.
2787
2919
  */
@@ -2971,6 +3103,8 @@ declare class ConversationClient extends BaseClient {
2971
3103
  type: 'CUSTOMER' | 'AI_AGENT' | 'HUMAN_AGENT';
2972
3104
  addresses: ConversationAddress[];
2973
3105
  }>;
3106
+ /** Conversation metadata (string values; CO allows at most 8 keys). */
3107
+ metadata?: Record<string, string>;
2974
3108
  }): Promise<ConversationResponse>;
2975
3109
  /**
2976
3110
  * Create a conversation with inline participants, reusing an existing active
@@ -2978,11 +3112,15 @@ declare class ConversationClient extends BaseClient {
2978
3112
  *
2979
3113
  * On 409 CO returns the existing conversation ID in the
2980
3114
  * X-Conflicting-Resource-Id response header.
3115
+ *
3116
+ * @param participants - Participants to create with the conversation
3117
+ * @param metadata - Set at creation; not applied when an existing
3118
+ * conversation is reused — the caller patches it
2981
3119
  */
2982
3120
  createOrReuseConversation(participants: Array<{
2983
3121
  type: 'CUSTOMER' | 'AI_AGENT' | 'HUMAN_AGENT';
2984
3122
  addresses: ConversationAddress[];
2985
- }>): Promise<{
3123
+ }>, metadata?: Record<string, string>): Promise<{
2986
3124
  conversation: {
2987
3125
  id: string;
2988
3126
  };
@@ -3054,6 +3192,24 @@ declare class ConversationClient extends BaseClient {
3054
3192
  * @returns Promise containing updated conversation
3055
3193
  */
3056
3194
  updateConversation(conversationId: string, status: 'ACTIVE' | 'INACTIVE' | 'CLOSED'): Promise<ConversationResponse>;
3195
+ /**
3196
+ * Fetch a conversation, including its metadata.
3197
+ *
3198
+ * @param conversationId - The conversation ID to fetch
3199
+ */
3200
+ getConversation(conversationId: string): Promise<ConversationResponse>;
3201
+ /**
3202
+ * Merge `metadata` into a conversation's metadata.
3203
+ *
3204
+ * A `PATCH` with only the given keys: other keys already on the conversation
3205
+ * are kept. Conversation Orchestrator rejects metadata changes once the
3206
+ * conversation is CLOSED.
3207
+ *
3208
+ * @param conversationId - The conversation ID to update
3209
+ * @param metadata - Keys to set (string values)
3210
+ * @returns The conversation, with its merged metadata
3211
+ */
3212
+ patchConversationMetadata(conversationId: string, metadata: Record<string, string>): Promise<ConversationResponse>;
3057
3213
  /**
3058
3214
  * Retrieve the details for a single configuration
3059
3215
  *
@@ -3111,7 +3267,7 @@ interface BaseChannelOptions {
3111
3267
  *
3112
3268
  * - "never": Memory is not automatically retrieved. Use the memory TAC tool or manually call `tac.retrieveMemory()` in callbacks for conditional retrieval.
3113
3269
  * - "always": Memory is automatically retrieved (using the message as query) for every inbound message and available in `onMessageReady` callback.
3114
- * - "once": Memory is retrieved once at conversation start with no query (and no conversation id) and cached on the session. Subsequent messages reuse the cache until the conversation becomes INACTIVE.
3270
+ * - "once" (Voice only): Memory is retrieved once at conversation start with no query (and no conversation id) and cached on the session. Subsequent prompts reuse the cache until the conversation becomes INACTIVE. Deprecated on messaging channels (removed in 3.0), which run it as "always".
3115
3271
  */
3116
3272
  memoryMode?: MemoryMode;
3117
3273
  /**
@@ -3123,12 +3279,13 @@ interface BaseChannelOptions {
3123
3279
  /**
3124
3280
  * Abstract base class for all channel implementations
3125
3281
  *
3126
- * Provides common functionality for:
3127
- * - Conversation lifecycle management and session tracking
3128
- * - Webhook deduplication using Twilio idempotency tokens
3129
- * - Event filtering to prevent cross-channel fanout
3130
- * - Memory retrieval integration
3131
- * - Error handling and logging
3282
+ * Provides only what every channel family shares: webhook deduplication,
3283
+ * event filtering to prevent cross-channel fanout, lifecycle analytics from
3284
+ * Conversation Orchestrator webhooks, memory retrieval, and error handling.
3285
+ *
3286
+ * Session storage deliberately isn't here. `VoiceChannel` owns its sessions (a
3287
+ * call is pinned to the process holding its WebSocket); messaging channels
3288
+ * derive a session per webhook and hold nothing between them.
3132
3289
  *
3133
3290
  * Subclasses must implement channel-specific webhook processing and message sending.
3134
3291
  */
@@ -3137,8 +3294,9 @@ declare abstract class BaseChannel {
3137
3294
  protected readonly config: TACConfig;
3138
3295
  protected readonly logger: Logger;
3139
3296
  protected readonly conversationClient: ConversationClient | null;
3140
- protected readonly activeConversations: Map<ConversationId, ConversationSession>;
3141
3297
  protected readonly callbacks: BaseChannelEvents;
3298
+ /** TAC's forwarder to `tac.onConversationEnded`, while it fills the slot. */
3299
+ private tacConversationEndedForwarder;
3142
3300
  protected readonly memoryMode: MemoryMode;
3143
3301
  private readonly processedWebhookTokens;
3144
3302
  private readonly maxTrackedTokens;
@@ -3147,6 +3305,17 @@ declare abstract class BaseChannel {
3147
3305
  * Get the channel type (implemented by subclasses)
3148
3306
  */
3149
3307
  abstract get channelType(): ChannelType;
3308
+ /**
3309
+ * Resolve the outbound sender address for this channel.
3310
+ *
3311
+ * `requested` (the caller's `options.from`) wins when it is one of the
3312
+ * channel's configured senders; otherwise throws. When omitted, the channel
3313
+ * default is used.
3314
+ */
3315
+ protected resolveOutboundFrom(requested: string | undefined, options: {
3316
+ allowlist: string[];
3317
+ default: string | undefined;
3318
+ }): string;
3150
3319
  /**
3151
3320
  * Register event callbacks
3152
3321
  */
@@ -3156,29 +3325,89 @@ declare abstract class BaseChannel {
3156
3325
  */
3157
3326
  abstract processWebhook(payload: unknown): Promise<void>;
3158
3327
  /**
3159
- * Send a response back to the user (implemented by subclasses)
3328
+ * Send a response back to the user (implemented by subclasses).
3329
+ *
3330
+ * Accepts the conversation id or the turn's `ConversationSession`; messaging
3331
+ * channels send straight from a session, and rebuild one from the id.
3160
3332
  */
3161
- abstract sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
3333
+ abstract sendResponse(conversationId: ConversationId | ConversationSession, message: string, metadata?: Record<string, unknown>): Promise<void>;
3162
3334
  /**
3163
- * Start a new conversation session
3335
+ * Get a live conversation session held by this channel.
3336
+ *
3337
+ * Only `VoiceChannel` holds sessions (a call is pinned to one process); the
3338
+ * default returns `undefined`.
3164
3339
  */
3165
- protected startConversation(conversationId: ConversationId, profileId?: ProfileId, serviceId?: string): ConversationSession;
3340
+ getConversationSession(_conversationId: ConversationId): ConversationSession | undefined;
3166
3341
  /**
3167
- * End a conversation session.
3342
+ * Check if this channel holds a live session for a conversation. Only
3343
+ * `VoiceChannel` holds sessions; the default returns `false`.
3344
+ */
3345
+ isConversationActive(_conversationId: ConversationId): boolean;
3346
+ /**
3347
+ * This channel's type as Conversation Orchestrator writes it on participant
3348
+ * addresses (`SMS`, `WHATSAPP`, `VOICE`, …).
3168
3349
  *
3169
- * Triggers the onConversationEnded callback BEFORE removing the session,
3170
- * so the callback receives the full ConversationSession data.
3171
- * Errors in the callback do not prevent session cleanup.
3350
+ * @internal
3172
3351
  */
3173
- protected endConversation(conversationId: ConversationId): Promise<void>;
3352
+ protected get coChannel(): string;
3174
3353
  /**
3175
- * Get an active conversation session
3354
+ * Whether `address` is TAC's own address on this channel. Channels override
3355
+ * this; the default claims no address.
3356
+ *
3357
+ * @internal
3176
3358
  */
3177
- getConversationSession(conversationId: ConversationId): ConversationSession | undefined;
3359
+ protected isOwnCoAddress(_address: string): boolean;
3178
3360
  /**
3179
- * Check if a conversation is active
3361
+ * Report "Conversation Started" from a CO `PARTICIPANT_ADDED` event.
3362
+ *
3363
+ * Counts the customer joining on this channel: a `CUSTOMER`, or an `UNKNOWN`
3364
+ * participant that isn't TAC's own address (capture can add the customer
3365
+ * untyped). Each channel reports only its own channel type, so a webhook
3366
+ * handed to every channel counts once per channel.
3367
+ *
3368
+ * @internal
3180
3369
  */
3181
- isConversationActive(conversationId: ConversationId): boolean;
3370
+ protected trackConversationStarted(eventData: unknown): void;
3371
+ /**
3372
+ * Report "Conversation Ended" for a conversation CO closed.
3373
+ *
3374
+ * Reported once per process across channels, without a `channel` — see
3375
+ * `TAC.reportConversationEnded`. `durationMs` is CO's `updatedAt −
3376
+ * createdAt`; `undefined` leaves it out rather than guessing.
3377
+ *
3378
+ * @internal
3379
+ */
3380
+ protected trackConversationEnded(conversationId: string, durationMs: number | undefined): void;
3381
+ /**
3382
+ * Whether anything would receive `onConversationEnded`. Channels check this
3383
+ * before rebuilding a closed conversation's session from Conversation
3384
+ * Orchestrator: with no handler, there is nothing to hand it to.
3385
+ *
3386
+ * Registering with TAC fills the slot with a forwarder to
3387
+ * `tac.onConversationEnded`; while that forwarder is installed, ask TAC. A
3388
+ * handler set with `channel.on('conversationEnded', ...)` — before or after
3389
+ * registration — replaces it and counts on its own.
3390
+ *
3391
+ * @internal
3392
+ */
3393
+ protected hasConversationEndedHandler(): boolean;
3394
+ /**
3395
+ * Install TAC's forwarder to `tac.onConversationEnded` in this channel's
3396
+ * slot, remembering it so {@link hasConversationEndedHandler} can tell it
3397
+ * apart from a handler registered directly on the channel.
3398
+ *
3399
+ * @internal
3400
+ */
3401
+ setConversationEndedForwarderInternal(forwarder: NonNullable<BaseChannelEvents['onConversationEnded']>): void;
3402
+ /**
3403
+ * Fire `onConversationEnded` for a session, swallowing handler errors.
3404
+ *
3405
+ * A developer callback throwing must not abort the channel's own cleanup or
3406
+ * fail the webhook, so the error is logged and dropped here.
3407
+ *
3408
+ * @internal
3409
+ */
3410
+ protected triggerConversationEnded(session: ConversationSession): Promise<void>;
3182
3411
  /**
3183
3412
  * Handle errors with proper context
3184
3413
  */
@@ -3200,8 +3429,10 @@ declare abstract class BaseChannel {
3200
3429
  * Self-filtering: check if webhook event belongs to this channel.
3201
3430
  *
3202
3431
  * - COMMUNICATION_CREATED: require author.channel matches this channel type
3203
- * - CONVERSATION_UPDATED: only process if conversation is tracked locally
3204
- * - Other events: pass through
3432
+ * - Other events pass through, including CONVERSATION_UPDATED — the
3433
+ * per-channel handler filters that one. Filtering it here on locally
3434
+ * tracked state would drop it on any instance that didn't serve the
3435
+ * conversation's messages.
3205
3436
  */
3206
3437
  protected isEventForThisChannel(webhookData: ConversationWebhookPayload): boolean;
3207
3438
  /**
@@ -3258,13 +3489,6 @@ declare abstract class BaseChannel {
3258
3489
  * continues without memory context.
3259
3490
  */
3260
3491
  protected retrieveMemoryIfEnabled(session: ConversationSession, query?: string): Promise<TACMemoryResponse | undefined>;
3261
- /**
3262
- * Invalidate cached memory for "once" mode when a conversation becomes
3263
- * INACTIVE. Conversation Orchestrator updates memory on the INACTIVE
3264
- * transition, so the next message re-fetches fresh memory. No-op for other
3265
- * memory modes.
3266
- */
3267
- protected invalidateCachedMemory(conversationId: ConversationId): void;
3268
3492
  /**
3269
3493
  * Cleanup resources when shutting down
3270
3494
  */
@@ -3272,7 +3496,7 @@ declare abstract class BaseChannel {
3272
3496
  }
3273
3497
 
3274
3498
  interface TACOptions {
3275
- config?: TACConfig | TACConfigData;
3499
+ config?: TACConfig | TACConfigInput;
3276
3500
  logger?: Logger;
3277
3501
  }
3278
3502
  /**
@@ -3288,10 +3512,24 @@ type MessageReadyCallback = (params: {
3288
3512
  channel: ChannelType;
3289
3513
  abortSignal?: AbortSignal;
3290
3514
  }) => Promise<string | null | void> | string | null | void;
3515
+ /**
3516
+ * Callback registered with {@link TAC.onInterrupt}, invoked when the caller
3517
+ * interrupts the agent on a voice call.
3518
+ */
3291
3519
  type InterruptCallback = (params: {
3520
+ /** The interrupted conversation. */
3292
3521
  conversationId: ConversationId;
3522
+ /**
3523
+ * Text the agent had spoken when interrupted. `undefined` if
3524
+ * ConversationRelay doesn't report it.
3525
+ */
3293
3526
  utteranceUntilInterrupt: string | undefined;
3527
+ /**
3528
+ * How long the agent had been speaking, in milliseconds. `undefined` if
3529
+ * ConversationRelay doesn't report it.
3530
+ */
3294
3531
  durationUntilInterruptMs: number | undefined;
3532
+ /** The live session for the call. */
3295
3533
  session: ConversationSession;
3296
3534
  }) => Promise<void> | void;
3297
3535
  type ConversationEndedCallback = (params: {
@@ -3316,10 +3554,21 @@ declare class TAC {
3316
3554
  private messageReadyCallback?;
3317
3555
  private interruptCallback?;
3318
3556
  private conversationEndedCallback?;
3557
+ private readonly participantLookups;
3558
+ private readonly reportedEnded;
3319
3559
  private constructor();
3320
3560
  static create(options?: TACOptions): Promise<TAC>;
3321
3561
  /**
3322
- * Register a channel with the framework
3562
+ * Register a channel with the framework, routing its inbound messages to the
3563
+ * {@link TAC.onMessageReady} callback and shutting it down with {@link TAC.shutdown}.
3564
+ *
3565
+ * `TACServer` registers the channels passed to it (`voiceChannel` /
3566
+ * `messagingChannels`), so you only need this when wiring channels into your
3567
+ * own web framework instead of `TACServer`.
3568
+ *
3569
+ * Only one channel per type is registered: registering a different instance
3570
+ * of the same type shuts down and replaces the existing one. Registering the
3571
+ * same instance again is a no-op.
3323
3572
  */
3324
3573
  registerChannel(channel: BaseChannel): void;
3325
3574
  /**
@@ -3336,18 +3585,80 @@ declare class TAC {
3336
3585
  */
3337
3586
  onMessageReady(callback: MessageReadyCallback): void;
3338
3587
  /**
3339
- * Register callback for when user interrupts (voice channel)
3588
+ * Register callback invoked when the caller interrupts the agent on a voice call.
3589
+ *
3590
+ * Currently fired by the ConversationRelay voice provider. The callback receives
3591
+ * `conversationId`, the call's `session`, `utteranceUntilInterrupt` (the text the
3592
+ * agent had spoken when interrupted) and `durationUntilInterruptMs` (how long it
3593
+ * had been speaking); either of the last two may be `undefined` if
3594
+ * ConversationRelay doesn't report it. Errors thrown by the callback are logged,
3595
+ * not rethrown.
3596
+ *
3597
+ * @example
3598
+ * ```typescript
3599
+ * tac.onInterrupt(({ conversationId, utteranceUntilInterrupt, durationUntilInterruptMs }) => {
3600
+ * console.log(
3601
+ * `${conversationId} interrupted after ${durationUntilInterruptMs} ms: ` +
3602
+ * JSON.stringify(utteranceUntilInterrupt)
3603
+ * );
3604
+ * });
3605
+ * ```
3340
3606
  */
3341
3607
  onInterrupt(callback: InterruptCallback): void;
3342
3608
  /**
3343
3609
  * Register callback for when a conversation ends.
3344
3610
  *
3345
- * The callback is triggered by channels when a conversation is closed
3346
- * (e.g., SMS conversation status changed to CLOSED, or voice WebSocket
3347
- * disconnected). The callback receives the full ConversationSession before
3348
- * it is cleaned up.
3611
+ * Fires when Conversation Orchestrator closes a conversation, on whichever
3612
+ * replica receives the CLOSED webhook — so the session it receives is
3613
+ * rebuilt from Conversation Orchestrator's participant list (identity only:
3614
+ * `conversationId`, `profileId`, participants). On messaging, read the
3615
+ * conversation's stored metadata with `conversationMetadata(session)`.
3616
+ * Relay-only and Media
3617
+ * Streams voice calls have no CO conversation, so they fire it at WebSocket
3618
+ * teardown with the live session instead. For an orchestrated call's live
3619
+ * state (transcript, `metadata`), use `VoiceChannel.onCallEnded`.
3620
+ *
3621
+ * At-least-once across webhook retries and replicas, like `onMessageReady`.
3349
3622
  */
3350
3623
  onConversationEnded(callback: ConversationEndedCallback): void;
3624
+ /**
3625
+ * Whether an `onConversationEnded` handler is registered. Channels check this
3626
+ * before rebuilding a session from Conversation Orchestrator: with no
3627
+ * handler, there is nothing to hand it to.
3628
+ *
3629
+ * @internal
3630
+ */
3631
+ hasConversationEndedCallback(): boolean;
3632
+ /**
3633
+ * List a conversation's participants, shared across channels briefly.
3634
+ *
3635
+ * A CO webhook is handed to every channel, and several may need the same
3636
+ * conversation's participants — to rebuild a closed conversation's session
3637
+ * for `onConversationEnded`. Concurrent callers share one in-flight request, and
3638
+ * later callers reuse its result until a minute after the request started. A
3639
+ * failure isn't cached. Not for paths that need fresh participants, like
3640
+ * reconciliation or resolving a session by CallSid.
3641
+ *
3642
+ * @throws If Conversation Orchestrator isn't configured, or whatever
3643
+ * `listParticipants` throws.
3644
+ * @internal
3645
+ */
3646
+ listParticipantsShared(conversationId: string): Promise<ConversationParticipant[]>;
3647
+ /**
3648
+ * Report "Conversation Ended" for a conversation Conversation Orchestrator
3649
+ * closed, once per process.
3650
+ *
3651
+ * Every channel is handed the CLOSED webhook, and its payload doesn't say
3652
+ * which channel the conversation was on. Finding out would take a
3653
+ * participant lookup made only for telemetry, so the event carries no
3654
+ * `channel`: join it to "Conversation Started" on `conversation_id`. The
3655
+ * first channel to report a conversation wins; the rest are dropped.
3656
+ *
3657
+ * @param durationMs - CO's `updatedAt − createdAt`; `undefined` leaves it
3658
+ * out rather than guessing.
3659
+ * @internal
3660
+ */
3661
+ reportConversationEnded(conversationId: string, durationMs: number | undefined): void;
3351
3662
  /**
3352
3663
  * Whether Conversation Orchestrator is configured.
3353
3664
  * Returns false in voice-only mode.
@@ -3449,6 +3760,11 @@ declare function shutdownAnalytics(): Promise<void>;
3449
3760
  /**
3450
3761
  * Messaging channel configuration options.
3451
3762
  * Alias for BaseChannelOptions that can be extended by specific channel implementations.
3763
+ *
3764
+ * `memoryMode: "once"` is **deprecated** on messaging channels and removed in
3765
+ * 3.0. It caches a recall on a session that outlives one request, which
3766
+ * messaging channels don't keep, so it logs a warning and runs as `"always"`.
3767
+ * It's still supported on the Voice channel.
3452
3768
  */
3453
3769
  type MessagingChannelConfig = BaseChannelOptions;
3454
3770
  /**
@@ -3461,6 +3777,8 @@ interface MessagingChannelEvents extends BaseChannelEvents {
3461
3777
  message: string;
3462
3778
  author: string;
3463
3779
  userMemory: any;
3780
+ /** This turn's session, derived from the webhook. */
3781
+ session: ConversationSession;
3464
3782
  }) => void;
3465
3783
  }
3466
3784
  /**
@@ -3469,6 +3787,15 @@ interface MessagingChannelEvents extends BaseChannelEvents {
3469
3787
  * Provides shared webhook processing logic for messaging channels
3470
3788
  * (SMS and Chat) that use the Conversations Service webhooks.
3471
3789
  *
3790
+ * **Stateless by construction.** No conversation session is kept between
3791
+ * webhooks: each request derives its own `ConversationSession` from the
3792
+ * payload, config, and one `listParticipants` call it needs anyway. So any
3793
+ * replica can serve any webhook — no sticky sessions, no shared datastore. A
3794
+ * session lasts one turn, so `session.metadata` doesn't carry over to the next
3795
+ * message; keep state across turns in your own store, keyed by
3796
+ * `conversationId`. `conversationMetadata(session)` reads the metadata stored
3797
+ * on Conversation Orchestrator from any instance.
3798
+ *
3472
3799
  * Subclasses must implement:
3473
3800
  * - `isDefaultAgentAddress`: fast-path check for the channel's default agent address
3474
3801
  * - `getAgentAddress`: return the agent's `ConversationAddress` for a conversation
@@ -3479,6 +3806,12 @@ interface MessagingChannelEvents extends BaseChannelEvents {
3479
3806
  * promote a channel-matching UNKNOWN participant (not owning the agent
3480
3807
  * address) to CUSTOMER. Set `false` for channels where the customer is
3481
3808
  * identified author-driven (e.g. chat).
3809
+ * - `deriveInboundAgentFromRecipients`: if `true` (default), the inbound agent
3810
+ * address is derived from the webhook's recipient (which of TAC's configured
3811
+ * numbers was messaged), validated against the channel's allowlist. `true` for
3812
+ * phone-like channels (SMS, RCS, WhatsApp). Set `false` for channels where the
3813
+ * agent is a single identity rather than a number set (e.g. chat), which keeps
3814
+ * the default-address path instead.
3482
3815
  */
3483
3816
  declare abstract class MessagingChannel extends BaseChannel {
3484
3817
  protected readonly conversationClient: ConversationClient;
@@ -3488,20 +3821,59 @@ declare abstract class MessagingChannel extends BaseChannel {
3488
3821
  * participant to CUSTOMER. Subclasses override to opt out (e.g. chat).
3489
3822
  */
3490
3823
  protected reconcileCustomerType: boolean;
3824
+ /**
3825
+ * Phone-like channels derive the agent address from the inbound webhook's
3826
+ * recipient (which of TAC's numbers was messaged). Chat uses a single identity
3827
+ * and opts out, keeping the default-address path.
3828
+ */
3829
+ protected deriveInboundAgentFromRecipients: boolean;
3830
+ /**
3831
+ * The uppercase Conversation Orchestrator channel name for this channel (e.g.
3832
+ * `"SMS"`, `"RCS"`), used to filter webhook recipients and participant
3833
+ * addresses. Derived from {@link channelType}.
3834
+ */
3835
+ protected getChannelName(): ParticipantAddressType;
3491
3836
  constructor(tac: TAC, config?: MessagingChannelConfig);
3492
3837
  /**
3493
- * Fast-path check: is the author address this channel's default agent address?
3494
- * (e.g., config.phoneNumber for SMS, agentAddress for Chat)
3838
+ * Fast-path check: is the author address one of this channel's configured agent addresses?
3839
+ *
3840
+ * Checks the channel's full sender allowlist, not just the default sender:
3841
+ * `config.phoneNumbers` for SMS, `config.rcsSenderIds` for RCS,
3842
+ * `config.whatsappNumbers` for WhatsApp, and `agentAddress` for Chat.
3495
3843
  */
3496
3844
  protected abstract isDefaultAgentAddress(authorAddress: string): boolean;
3497
3845
  /**
3498
3846
  * Return the agent-side ConversationAddress for this conversation.
3499
3847
  *
3500
- * Used by `reconcileParticipants` to identify which participant (by channel
3501
- * + address) represents the agent. May read from session state (e.g. chat's
3502
- * per-conversation channelId) to build the address.
3848
+ * Identifies which participant represents the agent, and supplies the
3849
+ * `from` address for outbound sends.
3503
3850
  */
3504
3851
  protected abstract getAgentAddress(conversationId: ConversationId): ConversationAddress;
3852
+ /**
3853
+ * The agent-side address for `session`; what TAC's own paths call.
3854
+ *
3855
+ * Defaults to `getAgentAddress(session.conversationId)`, so a subclass
3856
+ * overriding only that keeps working. Channels whose address depends on
3857
+ * per-conversation data (chat's `channelId`) override this to read the
3858
+ * session directly.
3859
+ */
3860
+ protected agentAddressFor(session: ConversationSession): ConversationAddress;
3861
+ protected isOwnCoAddress(address: string): boolean;
3862
+ /**
3863
+ * Messaging channels keep no sessions between webhooks, so there is nothing
3864
+ * to look up: always `undefined`.
3865
+ *
3866
+ * @deprecated Use the session `onMessageReady` (or
3867
+ * `initiateOutboundConversation`) hands you. Removed in 3.0.
3868
+ */
3869
+ getConversationSession(_conversationId: ConversationId): undefined;
3870
+ /**
3871
+ * Messaging channels keep no sessions between webhooks: always `false`.
3872
+ *
3873
+ * @deprecated Messaging channels are stateless; track conversations in your
3874
+ * own store, keyed by `conversationId`. Removed in 3.0.
3875
+ */
3876
+ isConversationActive(_conversationId: ConversationId): false;
3505
3877
  /**
3506
3878
  * Report a delivered response.
3507
3879
  *
@@ -3511,30 +3883,140 @@ declare abstract class MessagingChannel extends BaseChannel {
3511
3883
  */
3512
3884
  protected trackResponseSent(conversationId: ConversationId): void;
3513
3885
  /**
3514
- * Check if a message is from the bot itself (2-tier).
3886
+ * Whether the author is TAC, judged from an already-fetched participant list.
3515
3887
  *
3516
- * 1. Default agent address (stateless, no API call)
3517
- * 2. API fallback via listParticipants (cross-process / multi-worker)
3888
+ * The caller does the free check (author address is a configured agent
3889
+ * address) first; this catches TAC speaking from some other address.
3518
3890
  */
3519
3891
  private isOwnMessage;
3892
+ /**
3893
+ * Fetch a conversation's participants, returning `null` on failure.
3894
+ *
3895
+ * One call per inbound message, shared by the self-message check,
3896
+ * reconciliation, and profile resolution. None of them can proceed without
3897
+ * it, so a failure is a hard stop for the caller.
3898
+ */
3899
+ protected listParticipantsOrNull(conversationId: ConversationId): Promise<ConversationParticipant[] | null>;
3900
+ /**
3901
+ * Build an Actions API participant reference.
3902
+ *
3903
+ * Conversation Orchestrator resolves by participant id or by explicit
3904
+ * `(channel, address)`. Prefer the id — reconciliation has already
3905
+ * established it — and fall back to the address when there isn't one.
3906
+ */
3907
+ protected participantRef(address: string | undefined, participantId: string | undefined): ActionParticipantRef;
3908
+ /** A fresh, empty session for one turn of `conversationId` on this channel. */
3909
+ protected newSession(conversationId: string): ConversationSession;
3910
+ /** Whether `p` holds `address` on `channel`. */
3911
+ private ownsAddress;
3912
+ /**
3913
+ * Build a session for a conversation from its participants.
3914
+ *
3915
+ * Used where no inbound webhook is in hand: a CLOSED webhook, or
3916
+ * `sendResponse` given a bare id. Returns `null` when no participant is on
3917
+ * this channel, which is how another channel's conversation is filtered out.
3918
+ */
3919
+ protected sessionFromParticipants(conversationId: string, participants: ConversationParticipant[]): ConversationSession | null;
3920
+ /**
3921
+ * Resolve the session a `sendResponse` call replies within.
3922
+ *
3923
+ * A session is used as-is — it already carries both participants. A bare id
3924
+ * costs a `listParticipants` call to rebuild one, since the channel keeps no
3925
+ * session to look up.
3926
+ *
3927
+ * @throws If the participants can't be read, or no recipient resolves.
3928
+ */
3929
+ protected resolveSendSession(target: ConversationId | ConversationSession): Promise<ConversationSession & {
3930
+ authorInfo: AuthorInfo;
3931
+ }>;
3932
+ /**
3933
+ * The `channelSettings` for a reply within `session`, if any.
3934
+ *
3935
+ * Default (SMS, RCS, WhatsApp): `channelId` is optional and passed through
3936
+ * when the session carries one. Chat overrides this, since `channelId` is
3937
+ * required for delivery there.
3938
+ */
3939
+ protected buildChannelSettings(session: ConversationSession): ActionChannelSettings | undefined;
3940
+ /**
3941
+ * Send a text response using the Conversation Orchestrator Actions API
3942
+ * (SEND_MESSAGE).
3943
+ *
3944
+ * **Pass the session, not the id.** Hand back the one `onMessageReady` gave
3945
+ * you (or that `initiateOutboundConversation` returned) and the send costs no
3946
+ * extra API call — it already carries both participants. A bare id still
3947
+ * works, but the channel keeps no session to look up, so it spends a
3948
+ * `listParticipants` call rebuilding one.
3949
+ *
3950
+ * @param conversationIdOrSession - The `ConversationSession` to reply within
3951
+ * (preferred), or the conversation id.
3952
+ * @param message - Message content.
3953
+ * @param metadata - Optional metadata, passed to `onError` on failure.
3954
+ * @throws If no recipient can be resolved for the conversation, or the send
3955
+ * fails.
3956
+ */
3957
+ sendResponse(conversationIdOrSession: ConversationId | ConversationSession, message: string, metadata?: Record<string, unknown>): Promise<void>;
3520
3958
  /**
3521
3959
  * Register event callbacks (override for messaging-specific events)
3522
3960
  */
3523
3961
  on(event: string, callback: (...args: any[]) => void): void;
3524
3962
  /**
3525
- * Process messaging channel webhook from Conversation Orchestrator
3963
+ * Process messaging channel webhook from Conversation Orchestrator.
3964
+ *
3965
+ * Handles:
3966
+ *
3967
+ * - `COMMUNICATION_CREATED`: process an incoming message from the customer
3968
+ * - `CONVERSATION_UPDATED`: fire `onConversationEnded` and report
3969
+ * "Conversation Ended" when the conversation closes
3970
+ * - `PARTICIPANT_ADDED`: report "Conversation Started" when the customer
3971
+ * joins on this channel
3972
+ *
3973
+ * Any replica can handle any webhook. The idempotency cache is per-process,
3974
+ * though, so a Twilio retry landing on a different replica is processed
3975
+ * again, and `onMessageReady` can run twice for the same message. Retries
3976
+ * are rare when the webhook is acknowledged before processing, as
3977
+ * `TACServer` does.
3526
3978
  */
3527
3979
  processWebhook(payload: unknown, idempotencyToken?: string): Promise<void>;
3528
3980
  /**
3529
- * Handle conversation creation event
3981
+ * A loader that fetches a conversation's CO metadata, for
3982
+ * `conversationMetadata(session)`. The session keeps the result, so for its
3983
+ * turn only.
3984
+ */
3985
+ private coMetadataLoader;
3986
+ /**
3987
+ * Build this request's session from the webhook payload and config.
3988
+ *
3989
+ * Network-free — the author, the agent address and `channelId` are all in
3990
+ * hand already. Reconciliation layers the participant ids on after.
3991
+ * `inboundAgentAddress` is the sender the customer messaged, when the webhook
3992
+ * names it; otherwise the channel default stands in until the caller
3993
+ * resolves it.
3530
3994
  */
3531
- private handleConversationCreated;
3995
+ private resolveSession;
3532
3996
  /**
3533
3997
  * Handle new communication event (incoming message)
3534
3998
  */
3535
3999
  private handleCommunicationCreated;
3536
4000
  /**
3537
- * Handle conversation updated event
4001
+ * Resolve both sides of this turn from the participant list.
4002
+ *
4003
+ * Returns `false` when the message must not be answered: it's TAC's own, or
4004
+ * reconciliation failed (dropped, surfaced through `onError`).
4005
+ */
4006
+ private resolveParticipants;
4007
+ /**
4008
+ * Handle conversation updated event.
4009
+ *
4010
+ * Only CLOSED is acted on: it reports "Conversation Ended", from the payload
4011
+ * alone and once across channels, and fires `onConversationEnded`. Only a
4012
+ * registered handler costs a participant lookup — shared with the other
4013
+ * channels handling the same webhook — which confirms the conversation is on
4014
+ * this channel (a CHAT close must not fire on SMS) and lets this work on
4015
+ * whichever replica Twilio picked.
4016
+ *
4017
+ * The session is rebuilt the same way on every replica. The conversation's
4018
+ * CO metadata is read through `conversationMetadata(session)`: answered from
4019
+ * the payload when it carries metadata, otherwise fetched on demand.
3538
4020
  */
3539
4021
  private handleConversationUpdated;
3540
4022
  /**
@@ -3570,12 +4052,30 @@ declare abstract class MessagingChannel extends BaseChannel {
3570
4052
  * (via `session.authorInfo.participantId`), so promoting some other
3571
4053
  * `UNKNOWN` CHAT participant could pick the wrong recipient.
3572
4054
  *
4055
+ * @param session - Supplies the conversation id and the agent address to
4056
+ * match on — the sender the customer messaged, already resolved on
4057
+ * `session.aiAgentInfo`.
4058
+ * @param participants - Already fetched by the caller; reusing that response
4059
+ * is what makes running this on every message free.
3573
4060
  * @returns `[agent, customerOrNull]` on success. `customer` is `null` when
3574
4061
  * `reconcileCustomerType` is `false`. `null` overall when either the agent
3575
4062
  * or the customer cannot be resolved — the caller treats `null` as a hard
3576
4063
  * stop and skips the message-ready callback.
3577
4064
  */
3578
- protected reconcileParticipants(conversationId: ConversationId): Promise<[ConversationParticipant, ConversationParticipant | null] | null>;
4065
+ protected reconcileParticipants(session: ConversationSession, participants: ConversationParticipant[]): Promise<[ConversationParticipant, ConversationParticipant | null] | null>;
4066
+ /**
4067
+ * Resolve the agent address when the inbound webhook carried no recipient.
4068
+ *
4069
+ * Scans the conversation's participants for any of TAC's configured addresses
4070
+ * on this channel; falls back to the channel default when none is present.
4071
+ * Defensive path — the primary source is the webhook.
4072
+ */
4073
+ protected fallbackAgentAddress(session: ConversationSession, participants: ConversationParticipant[], channel: ParticipantAddressType): ConversationAddress;
4074
+ /**
4075
+ * The first of TAC's configured addresses on this channel that a participant
4076
+ * holds, if any.
4077
+ */
4078
+ protected ownedAgentAddress(participants: ConversationParticipant[], channel: ParticipantAddressType): string | undefined;
3579
4079
  /**
3580
4080
  * Find or mint a Conversation Memory profile for a customer being promoted from UNKNOWN.
3581
4081
  *
@@ -3614,8 +4114,14 @@ declare abstract class MessagingChannel extends BaseChannel {
3614
4114
  /**
3615
4115
  * Shared outbound conversation initiation for messaging channels (SMS/RCS/Chat/WhatsApp).
3616
4116
  *
3617
- * Handles the full flow: create conversation → find participants → start
3618
- * session → send initial message → error cleanup.
4117
+ * Handles the full flow: create conversation → find participants → build
4118
+ * session → send initial message → error cleanup. The session isn't kept by
4119
+ * the channel; it is returned to the caller.
4120
+ *
4121
+ * `metadata` entries with string values that fit Conversation Orchestrator's
4122
+ * limits are stored on the conversation (at creation; merged with a `PATCH`
4123
+ * when an existing conversation is reused), so `conversationMetadata()` can
4124
+ * read them on any replica. The rest stay on the returned session only.
3619
4125
  */
3620
4126
  protected initiateOutboundMessagingConversation(params: {
3621
4127
  channel: 'SMS' | 'CHAT' | 'RCS' | 'WHATSAPP';
@@ -3635,25 +4141,17 @@ declare abstract class MessagingChannel extends BaseChannel {
3635
4141
  * Automatically retrieves user memory and manages conversation lifecycle.
3636
4142
  */
3637
4143
  declare class SMSChannel extends MessagingChannel {
4144
+ constructor(tac: TAC, config?: MessagingChannelConfig);
3638
4145
  get channelType(): ChannelType;
3639
4146
  protected isDefaultAgentAddress(authorAddress: string): boolean;
3640
4147
  protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
3641
- /**
3642
- * Send SMS response using the Conversation Orchestrator Actions API (SEND_MESSAGE).
3643
- *
3644
- * Reads the agent and customer participant ids stashed on the session by
3645
- * inbound reconciliation or outbound initiation. Missing ids are a misuse —
3646
- * `sendResponse` is only expected to be called after an inbound webhook
3647
- * (COMMUNICATION_CREATED → reconcile) or after `initiateOutboundConversation`,
3648
- * both of which populate the session.
3649
- */
3650
- sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
3651
4148
  /**
3652
4149
  * Initiate an outbound SMS conversation
3653
4150
  *
3654
4151
  * Creates a conversation via Conversation Orchestrator, adds customer and
3655
4152
  * agent participants, then sends the initial message via the Actions API.
3656
- * The sender is always `config.phoneNumber`.
4153
+ * Uses `options.from` when provided (must be one of the configured phone
4154
+ * numbers), otherwise falls back to the default `config.phoneNumber`.
3657
4155
  */
3658
4156
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3659
4157
  }
@@ -3671,22 +4169,13 @@ declare class RCSChannel extends MessagingChannel {
3671
4169
  get channelType(): ChannelType;
3672
4170
  protected isDefaultAgentAddress(authorAddress: string): boolean;
3673
4171
  protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
3674
- /**
3675
- * Send RCS response using the Conversation Orchestrator Actions API (SEND_MESSAGE).
3676
- *
3677
- * Reads the agent and customer participant ids stashed on the session by
3678
- * inbound reconciliation or outbound initiation. Missing ids are a misuse —
3679
- * `sendResponse` is only expected to be called after an inbound webhook
3680
- * (COMMUNICATION_CREATED → reconcile) or after `initiateOutboundConversation`,
3681
- * both of which populate the session.
3682
- */
3683
- sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
3684
4172
  /**
3685
4173
  * Initiate an outbound RCS conversation
3686
4174
  *
3687
4175
  * Creates a conversation via Conversation Orchestrator, adds customer and
3688
4176
  * agent participants, then sends the initial message via the Actions API.
3689
- * The sender is always `config.rcsSenderId`.
4177
+ * Uses `options.from` when provided (must be one of the configured RCS
4178
+ * senders), otherwise falls back to the default `config.rcsSenderId`.
3690
4179
  */
3691
4180
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3692
4181
  }
@@ -3701,25 +4190,17 @@ declare class RCSChannel extends MessagingChannel {
3701
4190
  * (via TWILIO_WHATSAPP_NUMBER). Address format: whatsapp:+1234567890
3702
4191
  */
3703
4192
  declare class WhatsAppChannel extends MessagingChannel {
4193
+ constructor(tac: TAC, config?: MessagingChannelConfig);
3704
4194
  get channelType(): ChannelType;
3705
4195
  protected isDefaultAgentAddress(authorAddress: string): boolean;
3706
4196
  protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
3707
- /**
3708
- * Send WhatsApp response using the Conversation Orchestrator Actions API (SEND_MESSAGE).
3709
- *
3710
- * Reads the agent and customer participant ids stashed on the session by
3711
- * inbound reconciliation or outbound initiation. Missing ids are a misuse —
3712
- * `sendResponse` is only expected to be called after an inbound webhook
3713
- * (COMMUNICATION_CREATED → reconcile) or after `initiateOutboundConversation`,
3714
- * both of which populate the session.
3715
- */
3716
- sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
3717
4197
  /**
3718
4198
  * Initiate an outbound WhatsApp conversation
3719
4199
  *
3720
4200
  * Creates a conversation via Conversation Orchestrator, adds customer and
3721
4201
  * agent participants, then sends the initial message via the Actions API.
3722
- * The sender is always `config.whatsappNumber`.
4202
+ * Uses `options.from` when provided (must be one of the configured WhatsApp
4203
+ * numbers), otherwise falls back to the default `config.whatsappNumber`.
3723
4204
  */
3724
4205
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3725
4206
  }
@@ -3754,20 +4235,22 @@ interface ChatChannelConfig extends MessagingChannelConfig {
3754
4235
  declare class ChatChannel extends MessagingChannel {
3755
4236
  private readonly agentAddress;
3756
4237
  protected reconcileCustomerType: boolean;
4238
+ protected deriveInboundAgentFromRecipients: boolean;
3757
4239
  constructor(tac: TAC, config?: ChatChannelConfig);
3758
4240
  get channelType(): ChannelType;
3759
4241
  protected isDefaultAgentAddress(authorAddress: string): boolean;
3760
- protected getAgentAddress(conversationId: ConversationId): ConversationAddress;
4242
+ protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
4243
+ protected agentAddressFor(session: ConversationSession): ConversationAddress;
4244
+ private chatAddress;
3761
4245
  /**
3762
- * Send chat response using the Conversation Orchestrator Actions API (SEND_MESSAGE).
4246
+ * Rebuild the session, recovering `channelId` from the participants.
3763
4247
  *
3764
- * Reads the agent and customer participant ids stashed on the session by
3765
- * inbound reconciliation or outbound initiation. Missing ids are a misuse —
3766
- * `sendResponse` is only expected to be called after an inbound webhook
3767
- * (COMMUNICATION_CREATED → reconcile) or after `initiateOutboundConversation`,
3768
- * both of which populate the session.
4248
+ * A session rebuilt from a bare conversation id has no webhook to take
4249
+ * `channelId` from, so it's read off the customer's or agent's CHAT address
4250
+ * instead, where Conversation Orchestrator records it.
3769
4251
  */
3770
- sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
4252
+ protected sessionFromParticipants(conversationId: string, participants: ConversationParticipant[]): ConversationSession | null;
4253
+ protected buildChannelSettings(session: ConversationSession): ActionChannelSettings;
3771
4254
  /**
3772
4255
  * Initiate an outbound chat conversation
3773
4256
  *
@@ -3809,6 +4292,18 @@ declare class VoiceProvider {
3809
4292
  * `VoiceChannel` reports its `ChannelType`.
3810
4293
  */
3811
4294
  get channelName(): string;
4295
+ /**
4296
+ * Whether a Conversation Orchestrator `CLOSED` webhook will end this
4297
+ * provider's conversations.
4298
+ *
4299
+ * Decides who owns `onConversationEnded`. `false` (the default): no CO
4300
+ * conversation exists, so `VoiceChannel` fires it itself at teardown.
4301
+ * `true`: only `onCallEnded` fires at teardown and the CLOSED webhook — which
4302
+ * may reach another instance — does the rest.
4303
+ *
4304
+ * @internal
4305
+ */
4306
+ get conversationClosedByOrchestrator(): boolean;
3812
4307
  /**
3813
4308
  * Build the response for an inbound call. Default: not supported.
3814
4309
  *
@@ -3882,6 +4377,14 @@ declare class VoiceProvider {
3882
4377
  * never overwritten.
3883
4378
  */
3884
4379
  protected applyCallEventCallbacks(callParams: Record<string, unknown>): Record<string, unknown>;
4380
+ /**
4381
+ * Resolve the outbound caller ID for a voice call.
4382
+ *
4383
+ * Validates `requested` against `config.phoneNumbers`, defaulting to
4384
+ * `config.phoneNumber` — the same rule messaging channels apply via
4385
+ * `resolveOutboundSender`.
4386
+ */
4387
+ protected resolveFromNumber(requested: string | undefined): string;
3885
4388
  }
3886
4389
  /**
3887
4390
  * Base configuration for a {@link VoiceChannel}'s real-time media provider.
@@ -4033,6 +4536,14 @@ declare class ConversationRelayProvider extends VoiceProvider {
4033
4536
  private readonly MAX_INITIALIZATION_RETRIES;
4034
4537
  constructor(channel: VoiceChannel, tacConfig: TACConfig, config: ConversationRelayProviderConfig);
4035
4538
  get channelName(): string;
4539
+ /**
4540
+ * ConversationRelay asks Conversation Orchestrator to create the
4541
+ * conversation whenever TAC is orchestrated; in relay-only mode there is no
4542
+ * CO conversation and nothing will ever close it for us.
4543
+ *
4544
+ * @internal
4545
+ */
4546
+ get conversationClosedByOrchestrator(): boolean;
4036
4547
  /**
4037
4548
  * Get active WebSocket connection for a conversation
4038
4549
  */
@@ -4061,15 +4572,27 @@ declare class ConversationRelayProvider extends VoiceProvider {
4061
4572
  */
4062
4573
  private handleDtmfMessage;
4063
4574
  /**
4064
- * Handle WebSocket disconnection. In orchestrated mode the conversation stays
4065
- * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
4066
- * voice-only mode there is no such webhook, so it ends here.
4575
+ * Clean up WebSocket and session resources when the connection closes.
4576
+ *
4577
+ * Runs unconditionally — the call is over in every mode once its socket is
4578
+ * gone, so nothing local is kept waiting for a Conversation Orchestrator
4579
+ * webhook that may land on a different instance. Releasing the session fires
4580
+ * `onCallEnded` here and defers `onConversationEnded` to CO's CLOSED webhook
4581
+ * when orchestrated.
4582
+ *
4583
+ * Idempotent: a second run for a call already torn down does nothing.
4067
4584
  */
4068
4585
  private handleWebSocketDisconnect;
4069
4586
  /**
4070
4587
  * Send voice response via WebSocket
4071
4588
  */
4072
4589
  sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
4590
+ /**
4591
+ * Send the ConversationRelay `end` message if the session has a handoff
4592
+ * pending, so the caller is transferred once the response has been delivered.
4593
+ * No-op when nothing is pending.
4594
+ */
4595
+ private flushPendingHandoff;
4073
4596
  /**
4074
4597
  * Send a streaming voice response via WebSocket, token by token.
4075
4598
  *
@@ -4079,6 +4602,10 @@ declare class ConversationRelayProvider extends VoiceProvider {
4079
4602
  * interrupted), iteration stops and no final marker is sent (the interrupt
4080
4603
  * handler sends the finalization instead).
4081
4604
  *
4605
+ * Once the stream completes, a handoff pending on the session is delivered as
4606
+ * the WS `end` message, matching {@link sendResponse}. An aborted stream
4607
+ * leaves it pending for the next response.
4608
+ *
4082
4609
  * @returns The accumulated full response text.
4083
4610
  */
4084
4611
  sendStreamingResponse(conversationId: ConversationId, stream: AsyncIterable<string>, options?: {
@@ -4272,6 +4799,11 @@ type CallStatusHandler = (event: CallStatusEvent) => Promise<void> | void;
4272
4799
  type AmdHandler = (event: AmdEvent) => Promise<void> | void;
4273
4800
  /** Handler for Twilio `recordingStatusCallback` webhooks. */
4274
4801
  type RecordingHandler = (event: RecordingEvent) => Promise<void> | void;
4802
+ /**
4803
+ * Handler for a call's WebSocket teardown. Receives the live session just
4804
+ * before it is discarded — see {@link VoiceChannel.onCallEnded}.
4805
+ */
4806
+ type CallEndedHandler = (session: ConversationSession) => Promise<void> | void;
4275
4807
  /** One ConversationRelay keypress, as delivered to a {@link DtmfHandler}. */
4276
4808
  interface DtmfEvent {
4277
4809
  /**
@@ -4339,6 +4871,17 @@ declare class VoiceChannel extends BaseChannel {
4339
4871
  private onCallStatusHandler;
4340
4872
  private onAmdHandler;
4341
4873
  private onRecordingHandler;
4874
+ private onCallEndedHandler;
4875
+ /**
4876
+ * Live sessions by conversation id. Instance-local by design: a call is
4877
+ * pinned to the process holding its WebSocket.
4878
+ */
4879
+ private readonly activeConversations;
4880
+ /**
4881
+ * Live calls whose conversation CO already closed mid-call: their
4882
+ * `onConversationEnded` has fired, so teardown doesn't fire it again.
4883
+ */
4884
+ private readonly closedWhileLive;
4342
4885
  /**
4343
4886
  * @param tac - The owning {@link TAC} instance.
4344
4887
  * @param options - Either a {@link VoiceProviderConfig} selecting the media
@@ -4469,6 +5012,28 @@ declare class VoiceChannel extends BaseChannel {
4469
5012
  * ```
4470
5013
  */
4471
5014
  onDtmf(callback: DtmfHandler): void;
5015
+ /**
5016
+ * Register a handler for a call's WebSocket teardown.
5017
+ *
5018
+ * Fires once per call, always, on the instance that held the call. It
5019
+ * receives the live session just before it is discarded, so it is the only
5020
+ * place late-call in-memory state — the transcript, `callSid`, anything you
5021
+ * put on `metadata` — is still reachable.
5022
+ *
5023
+ * Not the same as `onConversationEnded` (fires when the *conversation*
5024
+ * closes, on any instance; on an orchestrated call, from a session rebuilt
5025
+ * from Conversation Orchestrator, identity only) or {@link onCallStatus} (a
5026
+ * Twilio Calls-API webhook, no session). Handler errors are logged and
5027
+ * swallowed.
5028
+ *
5029
+ * @example
5030
+ * ```typescript
5031
+ * voiceChannel.onCallEnded(async session => {
5032
+ * await archive(session.callSid, session.metadata.transcript ?? []);
5033
+ * });
5034
+ * ```
5035
+ */
5036
+ onCallEnded(callback: CallEndedHandler): void;
4472
5037
  /**
4473
5038
  * The registered call-event handlers, for a `VoiceProvider` deciding which
4474
5039
  * callback URLs to derive. A provider is not a subclass of `VoiceChannel`,
@@ -4529,19 +5094,18 @@ declare class VoiceChannel extends BaseChannel {
4529
5094
  */
4530
5095
  getInboundCallTwimlHandler(): InboundCallTwimlHandler | undefined;
4531
5096
  /**
4532
- * Start tracking a conversation session. Forwards to
4533
- * `BaseChannel.startConversation`.
5097
+ * Start tracking a call's session. Forwards to {@link startConversation}.
4534
5098
  *
4535
5099
  * @internal
4536
5100
  */
4537
5101
  startConversationInternal(conversationId: ConversationId, profileId?: ProfileId): ConversationSession;
4538
5102
  /**
4539
- * End a tracked conversation session. Forwards to
4540
- * `BaseChannel.endConversation`.
5103
+ * Release a finished call's session and fire the end-of-call hooks.
5104
+ * Forwards to {@link releaseSession}.
4541
5105
  *
4542
5106
  * @internal
4543
5107
  */
4544
- endConversationInternal(conversationId: ConversationId): Promise<void>;
5108
+ releaseSessionInternal(conversationId: ConversationId): Promise<ConversationSession | undefined>;
4545
5109
  /**
4546
5110
  * Retrieve memory when `memoryMode` calls for it. Forwards to
4547
5111
  * `BaseChannel.retrieveMemoryIfEnabled`.
@@ -4563,13 +5127,28 @@ declare class VoiceChannel extends BaseChannel {
4563
5127
  */
4564
5128
  on(event: string, callback: (...args: any[]) => void): void;
4565
5129
  /**
4566
- * Process conversation webhooks for cleanup.
4567
- *
4568
- * Voice channel processes CONVERSATION_UPDATED events:
4569
- * - CLOSED status: Clean up local session state
4570
- *
4571
- * Note: Conversation tracking uses instance-local memory. In multi-instance
4572
- * deployments, webhooks may route to a different instance, preventing cleanup.
5130
+ * Process Conversation Orchestrator webhooks.
5131
+ *
5132
+ * Voice channel processes these events:
5133
+ *
5134
+ * - **PARTICIPANT_ADDED**: report "Conversation Started" when the customer
5135
+ * joins on voice (orchestrated ConversationRelay only).
5136
+ * - **CLOSED** (CONVERSATION_UPDATED): fire `onConversationEnded`. The call's
5137
+ * session is normally already released (the WebSocket closed when the
5138
+ * caller hung up), so this rebuilds it from Conversation Orchestrator —
5139
+ * which is also what makes the hook fire on whichever instance received the
5140
+ * webhook rather than only on the one that held the call. If this instance
5141
+ * still holds the call's session (the call is live), the hook fires now
5142
+ * instead, with a snapshot of that live session, and the session stays
5143
+ * until the call's own teardown — which still fires {@link onCallEnded}. A
5144
+ * single call can then produce a second `onConversationEnded`, under a
5145
+ * different conversation id, when Conversation Orchestrator later closes
5146
+ * the conversation it started for the call's remaining traffic. It also
5147
+ * reports "Conversation Ended", with CO's duration, from the payload alone
5148
+ * and once across channels; only a registered handler costs the lookup.
5149
+ * - **INACTIVE**: invalidate cached memory, if this instance holds the
5150
+ * session. A call is pinned to one instance for its lifetime, so an
5151
+ * INACTIVE landing elsewhere has no cache to clear and is ignored.
4573
5152
  *
4574
5153
  * @param payload - Raw webhook event data from Twilio
4575
5154
  * @param idempotencyToken - Optional Twilio idempotency token from request headers
@@ -4579,6 +5158,91 @@ declare class VoiceChannel extends BaseChannel {
4579
5158
  * Handle conversation updated event
4580
5159
  */
4581
5160
  private handleConversationUpdated;
5161
+ /**
5162
+ * Get the live session this instance holds for a conversation.
5163
+ */
5164
+ getConversationSession(conversationId: ConversationId): ConversationSession | undefined;
5165
+ /**
5166
+ * Whether this instance holds a live session for a conversation.
5167
+ */
5168
+ isConversationActive(conversationId: ConversationId): boolean;
5169
+ /**
5170
+ * Track a new session for a call, or return the existing one.
5171
+ */
5172
+ protected startConversation(conversationId: ConversationId, profileId?: ProfileId): ConversationSession;
5173
+ /**
5174
+ * Free a finished call's session and fire the end-of-call hooks.
5175
+ *
5176
+ * Called from every teardown path and idempotent, so a second call is a
5177
+ * no-op returning `undefined`. Always fires {@link onCallEnded}. Also fires
5178
+ * `onConversationEnded` unless a Conversation Orchestrator CLOSED webhook will
5179
+ * do that later (see `VoiceProvider.conversationClosedByOrchestrator`).
5180
+ * Nothing is kept for that CLOSED: it gets a session rebuilt from
5181
+ * Conversation Orchestrator.
5182
+ */
5183
+ protected releaseSession(conversationId: ConversationId): Promise<ConversationSession | undefined>;
5184
+ /**
5185
+ * Fire `onConversationEnded` for a CLOSED webhook.
5186
+ *
5187
+ * The call has normally ended by now (the socket closed when the caller hung
5188
+ * up, or {@link endCall} hung it up), and its session went with it. The hook
5189
+ * gets a session rebuilt from Conversation Orchestrator, identity only,
5190
+ * which is what lets it fire on whichever instance received the webhook. The
5191
+ * call's live state (transcript, `metadata`) reached {@link onCallEnded} at
5192
+ * teardown.
5193
+ *
5194
+ * If this instance still holds the session, the call is live: CO closed the
5195
+ * conversation mid-call (a closed timeout during a long hold, or the app
5196
+ * closing it). The hook fires now, from a snapshot, and the session stays for
5197
+ * the call's own teardown to release — which is what keeps `onCallEnded`
5198
+ * firing and the rest of the call working. The call then carries on under
5199
+ * the closed conversation's id; CO starts a new conversation for its later
5200
+ * traffic, whose own CLOSED arrives here later and takes the rebuild path.
5201
+ *
5202
+ * The hook is at-least-once: a duplicate CLOSED delivery that isn't deduped
5203
+ * by its idempotency token fires it again, same as `onMessageReady`.
5204
+ */
5205
+ private handleConversationClosed;
5206
+ /**
5207
+ * A copy of a live call's session that shares no mutable state with it.
5208
+ *
5209
+ * `onConversationEnded` may keep or edit what it's given while the call
5210
+ * carries on, so the callback-visible data — `metadata` and the nested
5211
+ * objects — is cloned. A value that can't be cloned (an app-owned handle, a
5212
+ * class instance whose methods a clone would lose) is shared rather than
5213
+ * failing the hook.
5214
+ */
5215
+ private detachedSnapshot;
5216
+ /**
5217
+ * The participant representing TAC's agent at `address` on voice: one that
5218
+ * owns the address AND has an agent type. A HUMAN_AGENT at that address is
5219
+ * someone else.
5220
+ */
5221
+ private static findVoiceAgent;
5222
+ /**
5223
+ * Reconstruct a session from Conversation Orchestrator.
5224
+ *
5225
+ * Carries identity only — conversation id, `callSid`, profile, both
5226
+ * participants. Live in-memory state (transcript, metadata) isn't available
5227
+ * here; it reaches {@link onCallEnded}. `callSid` defaults to a VOICE
5228
+ * participant address's `channelId` — the customer's if present, else the
5229
+ * agent's, else any other participant's. Returns `undefined` if no
5230
+ * participant is on the voice channel, which is how another channel's CLOSED
5231
+ * is filtered out.
5232
+ *
5233
+ * `shared` (the CLOSED path) shares the participant lookup with the other
5234
+ * channels handling the same webhook; other callers need fresh participants.
5235
+ */
5236
+ private rebuildSession;
5237
+ /**
5238
+ * This channel's participants are recorded by Conversation Orchestrator as
5239
+ * VOICE, whatever the provider's transport label.
5240
+ *
5241
+ * @internal
5242
+ */
5243
+ protected get coChannel(): string;
5244
+ /** @internal */
5245
+ protected isOwnCoAddress(address: string): boolean;
4582
5246
  /**
4583
5247
  * Get active WebSocket connection for a conversation
4584
5248
  */
@@ -4594,7 +5258,7 @@ declare class VoiceChannel extends BaseChannel {
4594
5258
  /**
4595
5259
  * Send voice response via WebSocket
4596
5260
  */
4597
- sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
5261
+ sendResponse(conversationIdOrSession: ConversationId | ConversationSession, message: string, metadata?: Record<string, unknown>): Promise<void>;
4598
5262
  /**
4599
5263
  * Send a streaming voice response through the active provider's transport,
4600
5264
  * token by token. Delegates to the active provider — see
@@ -4732,6 +5396,11 @@ declare class VoiceChannel extends BaseChannel {
4732
5396
  * hangs up while AMD is still resolving), and handlers shouldn't have to
4733
5397
  * guard against it.
4734
5398
  *
5399
+ * The session is released as on any hangup: {@link onCallEnded} fires now.
5400
+ * On an orchestrated call `onConversationEnded` fires later, when
5401
+ * Conversation Orchestrator's CLOSED webhook arrives; otherwise it fires now
5402
+ * too.
5403
+ *
4735
5404
  * @param callSid - Twilio Call SID (from a call event, the outbound result, or
4736
5405
  * `ConversationSession.callSid`).
4737
5406
  * @returns True if Twilio accepted the hangup, false if it failed (logged).
@@ -4751,10 +5420,10 @@ declare class VoiceChannel extends BaseChannel {
4751
5420
  * exist before the caller speaks — including before `onAmd` fires. Treat it
4752
5421
  * as racy and hang up with {@link endCall}, which needs no session.
4753
5422
  *
4754
- * At the other end, orchestrator mode keeps the session until Conversation
4755
- * Orchestrator's CLOSED webhook, so it outlives the call and `onCallStatus` /
4756
- * `onRecording` do resolve. Relay-only mode tears down on the
4757
- * ConversationRelay callback instead, which races them.
5423
+ * At the other end the session is released as soon as the call's WebSocket
5424
+ * closes, in every mode — so out-of-band events that arrive after the hangup
5425
+ * (`onCallStatus`, `onRecording`) generally find nothing here. Read
5426
+ * late-call state from the session {@link onCallEnded} hands you instead.
4758
5427
  *
4759
5428
  * @example
4760
5429
  * ```typescript
@@ -4769,10 +5438,59 @@ declare class VoiceChannel extends BaseChannel {
4769
5438
  * @param callSid - Twilio Call SID, e.g. from
4770
5439
  * `InitiateVoiceConversationResult.callSid` or a call event.
4771
5440
  * @returns The session, or `undefined` — not created yet, the call ended, or
4772
- * it landed on another instance (see the horizontal-scaling note in
4773
- * CLAUDE.md).
5441
+ * it landed on another instance. For the last case,
5442
+ * {@link resolveConversationSessionByCallSid} falls back to Conversation
5443
+ * Orchestrator.
4774
5444
  */
4775
5445
  getConversationSessionByCallSid(callSid: string): ConversationSession | undefined;
5446
+ /**
5447
+ * Look up a call's session on any instance, falling back to Conversation
5448
+ * Orchestrator when this instance doesn't hold the call.
5449
+ *
5450
+ * Out-of-band call events (`onCallStatus`, `onAmd`, `onRecording`) carry
5451
+ * only a CallSid and, without `TACConfig.instancePublicDomain`, can reach any
5452
+ * replica. This returns the live session when the call is held here — same
5453
+ * as {@link getConversationSessionByCallSid} — and otherwise, for a
5454
+ * ConversationRelay call in orchestrator mode, a session rebuilt from
5455
+ * Conversation Orchestrator.
5456
+ *
5457
+ * A rebuilt session carries identity only (conversation id, `callSid`,
5458
+ * profile, both participants), is not tracked, and can't be used with
5459
+ * {@link sendResponse}: the call's WebSocket is on another instance. If CO
5460
+ * holds several conversations for the call (it starts a new one when a
5461
+ * conversation closes mid-call), the active one wins, else the newest — this
5462
+ * rule applies only to the rebuild path. On the instance holding the call,
5463
+ * the live session is returned as-is, so after a mid-call close it still
5464
+ * carries the closed conversation's id while other instances return the new
5465
+ * one; correlate by `callSid` if you need a stable key.
5466
+ *
5467
+ * To tell live from rebuilt, check
5468
+ * `voiceChannel.getWebsocket(session.conversationId) !== null` — true only
5469
+ * for a session live on this instance. A rebuilt session's `startedAt` is
5470
+ * the rebuild time, not the call's, and its `metadata` is always empty.
5471
+ *
5472
+ * Cost: on a local miss this makes up to two Conversation Orchestrator
5473
+ * requests (list conversations, then participants). Prefer
5474
+ * {@link getConversationSessionByCallSid} on hot paths, or when
5475
+ * `TACConfig.instancePublicDomain` already routes call events to the
5476
+ * instance holding the call.
5477
+ *
5478
+ * @example
5479
+ * ```typescript
5480
+ * voiceChannel.onCallStatus(async event => {
5481
+ * const session = await voiceChannel.resolveConversationSessionByCallSid(event.callSid);
5482
+ * if (session) {
5483
+ * auditLog(session.conversationId, session.profileId, event.callStatus);
5484
+ * }
5485
+ * });
5486
+ * ```
5487
+ *
5488
+ * @param callSid - Twilio Call SID, e.g. from a call event.
5489
+ * @returns The live or rebuilt session, or `undefined` — relay-only or Media
5490
+ * Streams mode (no CO conversation behind the call), CO knows no
5491
+ * conversation for it, or the lookup failed (logged).
5492
+ */
5493
+ resolveConversationSessionByCallSid(callSid: string): Promise<ConversationSession | undefined>;
4776
5494
  /**
4777
5495
  * Narrow `provider` to the ConversationRelay implementation for the
4778
5496
  * ConversationRelay-only forwarders on this channel.
@@ -4871,16 +5589,19 @@ declare abstract class TwiMLBuilderBase<TChannelConfig = unknown> {
4871
5589
  */
4872
5590
  protected missingWebsocketUrlError(caller: string): Error;
4873
5591
  /**
4874
- * The WebSocket URL derived from `TACConfig.voicePublicDomain` +
4875
- * `TACConfig.voiceWebsocketPath`, or undefined when `voicePublicDomain` is
4876
- * unset.
5592
+ * The WebSocket URL derived from `TACConfig.voiceCallbackDomain` +
5593
+ * `TACConfig.voiceWebsocketPath`, or undefined when no public domain is set.
5594
+ *
5595
+ * Uses `voiceCallbackDomain`, so a deployment that sets
5596
+ * `instancePublicDomain` pins the call to this process from its very first
5597
+ * connection.
4877
5598
  */
4878
5599
  protected defaultWebsocketUrl(): string | undefined;
4879
5600
  /**
4880
5601
  * Resolve the default `<Connect action=...>` cleanup URL from
4881
- * `TACConfig.voicePublicDomain` + `TACConfig.voiceActionPath`.
5602
+ * `TACConfig.voiceCallbackDomain` + `TACConfig.voiceActionPath`.
4882
5603
  *
4883
- * Returns undefined if `voicePublicDomain` isn't set; that's fine because
5604
+ * Returns undefined if no public domain is set; that's fine because
4884
5605
  * actionUrl has higher-priority layers (customizer, twimlOptions, Studio
4885
5606
  * handoff) above this fallback.
4886
5607
  */
@@ -4946,7 +5667,7 @@ declare class TwiMLBuilderMediaStreams extends TwiMLBuilderBase<MediaStreamsTwiM
4946
5667
  * 2. the provider config's `defaultTwimlOptions` — channel-wide defaults
4947
5668
  * 3. `host` — per-call transport facts supplied by the host
4948
5669
  * 4. TAC defaults: the WebSocket URL derived from
4949
- * `TACConfig.voicePublicDomain` + `voiceWebsocketPath`
5670
+ * `TACConfig.voiceCallbackDomain` + `voiceWebsocketPath`
4950
5671
  *
4951
5672
  * @param caller - Name of the calling method, used in the "no WebSocket URL"
4952
5673
  * error so it points at the API the developer actually called.
@@ -4961,8 +5682,10 @@ declare class TwiMLBuilderMediaStreams extends TwiMLBuilderBase<MediaStreamsTwiM
4961
5682
  *
4962
5683
  * `customParameters` replaces wholesale when set at a higher-priority layer —
4963
5684
  * there's no per-key merging.
5685
+ *
5686
+ * @internal
4964
5687
  */
4965
- protected buildTwimlOptions(host: VoiceTwiMLOptionsMediaStreams | undefined, perCall: VoiceTwiMLOptionsMediaStreams | undefined): VoiceTwiMLOptionsMediaStreams;
5688
+ buildTwimlOptions(host: VoiceTwiMLOptionsMediaStreams | undefined, perCall: VoiceTwiMLOptionsMediaStreams | undefined): VoiceTwiMLOptionsMediaStreams;
4966
5689
  }
4967
5690
 
4968
5691
  /** Options accepted by {@link MediaStreamsProviderConfig}. */
@@ -5099,13 +5822,23 @@ interface SendMessageResult {
5099
5822
  }
5100
5823
  /**
5101
5824
  * Create send message tool
5825
+ *
5826
+ * **Pass the session, not the id.** Hand in the `ConversationSession` that
5827
+ * `onMessageReady` gave you and every send reuses it as-is. A bare id still
5828
+ * works, but messaging channels keep no sessions, so each send spends a
5829
+ * `listParticipants` call rebuilding one — and on chat, where the customer
5830
+ * stays `UNKNOWN`, that rebuild resolves no recipient and the send fails.
5831
+ *
5832
+ * @param channel - Channel to send through.
5833
+ * @param conversationIdOrSession - The `ConversationSession` to reply within
5834
+ * (preferred), or the conversation id.
5102
5835
  */
5103
- declare function createSendMessageTool(channel: BaseChannel, conversationId: ConversationId): TACTool<SendMessageParams, SendMessageResult>;
5836
+ declare function createSendMessageTool(channel: BaseChannel, conversationIdOrSession: ConversationId | ConversationSession): TACTool<SendMessageParams, SendMessageResult>;
5104
5837
  /**
5105
5838
  * Create factory function for messaging tools
5106
5839
  */
5107
5840
  declare function createMessagingTools(): {
5108
- forConversation: (channel: BaseChannel, conversationId: ConversationId) => TACTool<SendMessageParams, SendMessageResult>;
5841
+ forConversation: (channel: BaseChannel, conversationIdOrSession: ConversationId | ConversationSession) => TACTool<SendMessageParams, SendMessageResult>;
5109
5842
  };
5110
5843
 
5111
5844
  /**
@@ -5339,6 +6072,41 @@ declare class MediaStreamsOpenAICallState {
5339
6072
  modelReady: Promise<boolean> | null;
5340
6073
  }
5341
6074
 
6075
+ /**
6076
+ * A string-keyed map whose entries expire and whose size is bounded.
6077
+ *
6078
+ * For state one Twilio request creates and a later one for the same call
6079
+ * consumes. Normally deleted within seconds — but a call that is never
6080
+ * answered, or whose second request lands on another instance, leaves an entry
6081
+ * nobody will collect. The TTL and cap make that leak impossible rather than
6082
+ * unlikely. Expiry is lazy: no timers are armed, so nothing keeps the process
6083
+ * alive.
6084
+ *
6085
+ * @internal
6086
+ */
6087
+ declare class ExpiringMap<V> {
6088
+ private readonly ttlMs;
6089
+ private readonly maxEntries;
6090
+ private readonly entries;
6091
+ constructor(options?: {
6092
+ ttlMs?: number;
6093
+ maxEntries?: number;
6094
+ });
6095
+ /** Current time in ms; overridable in tests. */
6096
+ protected now(): number;
6097
+ /** Drop expired entries, then the oldest survivors if still over capacity. */
6098
+ private purge;
6099
+ set(key: string, value: V): this;
6100
+ get(key: string): V | undefined;
6101
+ has(key: string): boolean;
6102
+ /** Remove `key` and return its live value, if any. */
6103
+ take(key: string): V | undefined;
6104
+ delete(key: string): boolean;
6105
+ clear(): void;
6106
+ /** Number of live entries. */
6107
+ get size(): number;
6108
+ }
6109
+
5342
6110
  /**
5343
6111
  * Identifies this SDK to OpenAI on every WebSocket connection, per OpenAI's
5344
6112
  * requested User-Agent pattern: [Company/Library name]/[Language] [Version].
@@ -5374,21 +6142,16 @@ declare abstract class MediaStreamsOpenAIProvider<TCallState extends MediaStream
5374
6142
  protected readonly tacConfig: TACConfig;
5375
6143
  protected readonly twimlBuilder: TwiMLBuilderMediaStreams;
5376
6144
  /**
5377
- * Session config overrides awaiting the call they belong to.
6145
+ * Per-call session config overrides, minted by one Twilio request and
6146
+ * consumed when the call's WebSocket connects.
5378
6147
  *
5379
- * Inbound entries are keyed by call SID (known when the TwiML webhook is
5380
- * answered); a subclass keys its outbound entries by whatever token it round
5381
- * trips through the stream's custom parameters.
5382
- */
5383
- protected readonly pendingSessionConfigs: Map<string, Record<string, unknown>>;
5384
- /**
5385
- * Expiry timers for the inbound {@link pendingSessionConfigs} entries, keyed
5386
- * by the same call SID. Each fires once to purge a stash whose Media Stream
5387
- * never connected; a normal connect cancels it in the subclass's
5388
- * `registerCall`. Outbound entries are keyed by token instead and are not
5389
- * tracked here.
6148
+ * Keyed by a token that rides the TwiML's custom parameters, rekeyed to the
6149
+ * call's conversation id on connect ({@link claimSessionConfig}). Set in
6150
+ * `handleIncomingCall` or `initiateOutboundConversation`, consumed when the
6151
+ * model connects. Bounded and expiring, so a call that never connects
6152
+ * doesn't leave its entry here forever.
5390
6153
  */
5391
- private readonly pendingInboundExpiries;
6154
+ protected readonly pendingSessionConfigs: ExpiringMap<Record<string, unknown>>;
5392
6155
  constructor(channel: VoiceChannel, tacConfig: TACConfig, config: MediaStreamsOpenAIProviderConfig);
5393
6156
  /** The Twilio-facing WebSocket for a conversation, if one is tracked. */
5394
6157
  getWebSocket(conversationId: ConversationId): WebSocket | null;
@@ -5408,13 +6171,14 @@ declare abstract class MediaStreamsOpenAIProvider<TCallState extends MediaStream
5408
6171
  * The transcript captured so far for an in-progress call.
5409
6172
  *
5410
6173
  * It lives on `ConversationSession.metadata.transcript`, so once the call
5411
- * ends and the session is dropped it is no longer reachable here — read it
5412
- * from the session an `onConversationEnded` handler receives instead.
6174
+ * ends (and the session is released at WebSocket teardown) it is no longer
6175
+ * reachable here — read it from the session a `VoiceChannel.onCallEnded`
6176
+ * handler receives instead.
5413
6177
  */
5414
6178
  getTranscript(conversationId: ConversationId): Record<string, string>[];
5415
6179
  /**
5416
- * The session config stashed for `key` — a call SID for inbound calls, a
5417
- * token for outbound ones.
6180
+ * The session config stashed for `key` — a session-config token before the
6181
+ * call connects, its conversation id after.
5418
6182
  *
5419
6183
  * @internal
5420
6184
  */
@@ -5426,24 +6190,35 @@ declare abstract class MediaStreamsOpenAIProvider<TCallState extends MediaStream
5426
6190
  */
5427
6191
  pendingSessionConfigCount(): number;
5428
6192
  /**
5429
- * Start the clock on an inbound stash, so a call whose Media Stream never
5430
- * connects cannot strand its override in {@link pendingSessionConfigs} until
5431
- * shutdown.
6193
+ * Mint a fresh session-config token.
6194
+ *
6195
+ * @internal
6196
+ */
6197
+ protected static newSessionConfigToken(): string;
6198
+ /**
6199
+ * `perCall` with the session-config token added to the stream's custom
6200
+ * parameters.
5432
6201
  *
5433
- * Unref'd: a two-minute timer must not be what keeps the process alive after
5434
- * the call it belongs to is long over. Re-arming replaces any prior timer for
5435
- * the same call SID, so a duplicate inbound webhook can't orphan one.
6202
+ * The builder replaces whole fields, so the token is added to the parameters
6203
+ * the call would otherwise get — from `perCall`, `defaultTwimlOptions` or
6204
+ * `host`, by the builder's precedence — rather than to `perCall`'s alone,
6205
+ * which would drop inherited ones.
6206
+ *
6207
+ * @internal
5436
6208
  */
5437
- private armInboundConfigExpiry;
6209
+ protected withSessionConfigToken(host: VoiceTwiMLOptionsMediaStreams | undefined, perCall: VoiceTwiMLOptionsMediaStreams | undefined, token: string): VoiceTwiMLOptionsMediaStreams;
5438
6210
  /**
5439
- * Stop the clock on an inbound stash, once the call it belongs to has
5440
- * connected and is about to consume the entry. A no-op for outbound calls,
5441
- * which key their stash by token and never arm one — the subclass calls this
5442
- * with the call SID for every `start`, inbound or not.
6211
+ * Move the session config stashed under `token` to this call's id.
6212
+ *
6213
+ * A token this instance doesn't hold means the config was stashed on another
6214
+ * instance — the TwiML webhook or `initiateOutboundConversation` ran
6215
+ * somewhere other than where the stream connected — or it expired. The call
6216
+ * then falls back to `defaultSessionConfig`, so this warns: with multiple
6217
+ * instances, per-call session configs need `TACConfig.instancePublicDomain`.
5443
6218
  *
5444
6219
  * @internal
5445
6220
  */
5446
- protected cancelInboundConfigExpiry(callSid: string): void;
6221
+ protected claimSessionConfig(token: string | undefined, conversationId: ConversationId): void;
5447
6222
  /**
5448
6223
  * The executable tool the model would run for `name`, if the config supplied
5449
6224
  * one.
@@ -5463,12 +6238,14 @@ declare abstract class MediaStreamsOpenAIProvider<TCallState extends MediaStream
5463
6238
  * 3. `options.hostTwimlOptions` — per-call transport facts supplied by the
5464
6239
  * host
5465
6240
  * 4. TAC defaults: the WebSocket URL derived from
5466
- * `TACConfig.voicePublicDomain` + `voiceWebsocketPath`
6241
+ * `TACConfig.voiceCallbackDomain` + `voiceWebsocketPath`
5467
6242
  *
5468
6243
  * Also runs `MediaStreamsOpenAIProviderConfig.onInboundCallSessionConfig`, if
5469
- * set, and stashes its result for the call to pick up once it connects. The
5470
- * hook runs only after the TwiML builds, so a call that never connects
5471
- * leaves nothing stashed behind it.
6244
+ * set, and stashes its result for the call to pick up once it connects,
6245
+ * under a token carried on the stream's custom parameters — so the config is
6246
+ * found by the stream it belongs to rather than keyed to a call SID. The
6247
+ * stash is written only after the TwiML builds, so a webhook that fails
6248
+ * leaves nothing behind it.
5472
6249
  *
5473
6250
  * @param twimlRequest - Parsed Twilio webhook fields for the inbound call.
5474
6251
  * @param options - Additional per-call inputs.
@@ -5829,8 +6606,8 @@ declare class OpenAIRealtimeProvider extends MediaStreamsOpenAIProvider<CallStat
5829
6606
  */
5830
6607
  private handleFunctionCall;
5831
6608
  /**
5832
- * Drop this call's transport state, close the model socket, and end the
5833
- * session.
6609
+ * Drop this call's transport state and any stashed session config, close
6610
+ * the model socket, and release the session.
5834
6611
  *
5835
6612
  * Both legs can report the call ending, and the first one to arrive tears
5836
6613
  * down the other, so this runs at most once per call: a second invocation
@@ -5920,7 +6697,6 @@ declare class GPTLiveProvider extends MediaStreamsOpenAIProvider<CallState> {
5920
6697
  * rather than a second field that shadows it.
5921
6698
  */
5922
6699
  protected readonly config: GPTLiveProviderConfig;
5923
- private readonly pendingTokenExpiries;
5924
6700
  /** Calls whose teardown has begun but is still awaiting `session.closed`. */
5925
6701
  private readonly closingCalls;
5926
6702
  get channelName(): string;
@@ -5947,21 +6723,6 @@ declare class GPTLiveProvider extends MediaStreamsOpenAIProvider<CallState> {
5947
6723
  * `TACConfig.voicePublicDomain` is unset.
5948
6724
  */
5949
6725
  initiateOutboundConversation(options: InitiateVoiceConversationOptions | InitiateVoiceConversationOptionsGPTLive): Promise<InitiateVoiceConversationResult>;
5950
- /**
5951
- * Start the clock on a stashed token, so a call that never connects cannot
5952
- * strand its override in {@link pendingSessionConfigs} forever.
5953
- *
5954
- * Unref'd: a two-minute timer must not be what keeps the process alive after
5955
- * the call it belongs to is long over.
5956
- */
5957
- private armTokenExpiry;
5958
- /**
5959
- * Stop the clock on a token, once the call it belongs to has claimed it.
5960
- *
5961
- * Without this a two-minute timer outlives every call that connected
5962
- * normally, waiting to purge an entry that is already gone.
5963
- */
5964
- private cancelTokenExpiry;
5965
6726
  /**
5966
6727
  * Drive one Twilio Media Stream connection from `start` to disconnect.
5967
6728
  *
@@ -6038,10 +6799,6 @@ declare class GPTLiveProvider extends MediaStreamsOpenAIProvider<CallState> {
6038
6799
  /**
6039
6800
  * Drop this provider's transport state on channel shutdown, including the
6040
6801
  * bookkeeping it keeps beyond the base class's.
6041
- *
6042
- * The token expiry timers are unref'd and delete themselves, so nothing hangs
6043
- * without this — but a shut-down provider must not still be holding entries
6044
- * for calls that can no longer arrive.
6045
6802
  */
6046
6803
  shutdown(): void;
6047
6804
  /** Apply one parsed GPT-Live event to the call. */
@@ -6139,6 +6896,31 @@ declare class OperatorResultProcessor {
6139
6896
  private processSummaryEvent;
6140
6897
  }
6141
6898
 
6899
+ /**
6900
+ * The metadata stored on a conversation in Conversation Orchestrator.
6901
+ *
6902
+ * `session.metadata` is the session's own data, which another replica doesn't
6903
+ * see. This reads what's stored on the conversation itself — for example the
6904
+ * `metadata` passed to `initiateOutboundConversation` — so it works on
6905
+ * whichever replica handles the turn. It costs one Conversation Orchestrator
6906
+ * request, kept for the rest of this turn, unless the session already knows
6907
+ * it: the session `initiateOutboundConversation` returns holds what it wrote,
6908
+ * and a CLOSED webhook's session holds the payload's copy.
6909
+ *
6910
+ * Returns a copy, so editing it changes nothing. Returns `{}` when the
6911
+ * conversation has no metadata, the session didn't come from a channel, or the
6912
+ * lookup fails; a failed lookup is retried on the next call.
6913
+ *
6914
+ * @example
6915
+ * ```typescript
6916
+ * tac.onMessageReady(async ({ session }) => {
6917
+ * const metadata = await conversationMetadata(session);
6918
+ * const appointmentId = metadata.appointment_id;
6919
+ * });
6920
+ * ```
6921
+ */
6922
+ declare function conversationMetadata(session: ConversationSession): Promise<Record<string, string>>;
6923
+
6142
6924
  /**
6143
6925
  * Configuration options for adapter utilities like MemoryPromptBuilder.
6144
6926
  */
@@ -6299,9 +7081,18 @@ interface TACServerConfig {
6299
7081
  /** Path for Conversation Intelligence webhook (optional - only registered if provided) */
6300
7082
  cintel?: string;
6301
7083
  };
6302
- /** Voice channel instance (alternative to registering on TAC) */
7084
+ /**
7085
+ * Voice channel to serve. The server registers it on TAC (see
7086
+ * {@link TAC.registerChannel}), so it doesn't need registering separately.
7087
+ * Defaults to the voice channel already registered on TAC, if any.
7088
+ */
6303
7089
  voiceChannel?: VoiceChannel;
6304
- /** Messaging channel instances — webhooks are fanned out to all (alternative to registering on TAC) */
7090
+ /**
7091
+ * Messaging channels to serve; conversation webhooks are fanned out to all of
7092
+ * them. The server registers each on TAC (see {@link TAC.registerChannel}), so
7093
+ * they don't need registering separately. Defaults to the SMS, RCS, Chat and
7094
+ * WhatsApp channels already registered on TAC.
7095
+ */
6305
7096
  messagingChannels?: MessagingChannel[];
6306
7097
  }
6307
7098
  /**
@@ -6384,4 +7175,4 @@ declare class TACServer {
6384
7175
  stop(): Promise<void>;
6385
7176
  }
6386
7177
 
6387
- 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 BuildStreamTwiMLInputs, 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, ConversationRelayProvider, ConversationRelayProviderConfig, type ConversationRelayProviderConfigOptions, 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, GPTLiveProvider, GPTLiveProviderConfig, type GPTLiveProviderConfigOptions, GPT_LIVE_SESSION_ID_METADATA_KEY, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, type InitiateVoiceConversationOptionsGPTLive, InitiateVoiceConversationOptionsGPTLiveSchema, type InitiateVoiceConversationOptionsOpenAIRealtime, InitiateVoiceConversationOptionsOpenAIRealtimeSchema, 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, MediaStreamsOpenAICallState, MediaStreamsOpenAIProvider, MediaStreamsOpenAIProviderConfig, type MediaStreamsOpenAIProviderConfigOptions, MediaStreamsProviderConfig, type MediaStreamsProviderConfigOptions, type MediaStreamsTwiMLBuilderConfig, 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, OPENAI_USER_AGENT, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, OpenAIRealtimeProvider, OpenAIRealtimeProviderConfig, type OpenAIRealtimeProviderConfigOptions, type OpenAIRealtimeTool, OpenAIRealtimeToolSchema, 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 StreamStartMessage, StreamStartMessageSchema, 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, TWILIO_AUDIO_FORMAT_FOR_GPT_LIVE, TWILIO_AUDIO_FORMAT_FOR_REALTIME, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, TwiMLBuilderMediaStreams, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TwilioProviderCallbackResponse, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, VoiceProvider, VoiceProviderConfig, type VoiceTwiMLOptions, type VoiceTwiMLOptionsConversationRelay, VoiceTwiMLOptionsConversationRelaySchema, type VoiceTwiMLOptionsMediaStreams, VoiceTwiMLOptionsMediaStreamsSchema, VoiceTwiMLOptionsSchema, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, generateStreamTwiml, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, shutdownAnalytics, studioExecutionsUrl, studioVoiceHandoffUrl, trackEvent, twiMLRequestFromForm };
7178
+ 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 BuildStreamTwiMLInputs, type BuiltInToolName, BuiltInTools, CALL_EVENT_KINDS, type CallEndedHandler, 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, ConversationRelayProvider, ConversationRelayProviderConfig, type ConversationRelayProviderConfigOptions, 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, GPTLiveProvider, GPTLiveProviderConfig, type GPTLiveProviderConfigOptions, GPT_LIVE_SESSION_ID_METADATA_KEY, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, type InitiateVoiceConversationOptionsGPTLive, InitiateVoiceConversationOptionsGPTLiveSchema, type InitiateVoiceConversationOptionsOpenAIRealtime, InitiateVoiceConversationOptionsOpenAIRealtimeSchema, 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, MediaStreamsOpenAICallState, MediaStreamsOpenAIProvider, MediaStreamsOpenAIProviderConfig, type MediaStreamsOpenAIProviderConfigOptions, MediaStreamsProviderConfig, type MediaStreamsProviderConfigOptions, type MediaStreamsTwiMLBuilderConfig, 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, OPENAI_USER_AGENT, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, OpenAIRealtimeProvider, OpenAIRealtimeProviderConfig, type OpenAIRealtimeProviderConfigOptions, type OpenAIRealtimeTool, OpenAIRealtimeToolSchema, 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 StreamStartMessage, StreamStartMessageSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, type TACConfigInput, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, TWILIO_AUDIO_FORMAT_FOR_GPT_LIVE, TWILIO_AUDIO_FORMAT_FOR_REALTIME, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, TwiMLBuilderMediaStreams, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TwilioProviderCallbackResponse, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, VoiceProvider, VoiceProviderConfig, type VoiceTwiMLOptions, type VoiceTwiMLOptionsConversationRelay, VoiceTwiMLOptionsConversationRelaySchema, type VoiceTwiMLOptionsMediaStreams, VoiceTwiMLOptionsMediaStreamsSchema, VoiceTwiMLOptionsSchema, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, conversationMetadata, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, generateStreamTwiml, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, shutdownAnalytics, studioExecutionsUrl, studioVoiceHandoffUrl, trackEvent, twiMLRequestFromForm };