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/README.md +14 -12
- package/dist/index.d.ts +991 -200
- package/dist/index.js +2227 -1023
- package/dist/index.js.map +1 -1
- package/package.json +9 -5
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
|
1546
|
+
* Options for initiating an outbound messaging conversation (SMS/RCS/WhatsApp).
|
|
1467
1547
|
*
|
|
1468
|
-
* The sender
|
|
1469
|
-
*
|
|
1470
|
-
*
|
|
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
|
|
2228
|
-
*
|
|
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
|
-
|
|
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:
|
|
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
|
-
* -
|
|
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
|
-
*
|
|
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
|
|
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
|
|
3127
|
-
* -
|
|
3128
|
-
*
|
|
3129
|
-
*
|
|
3130
|
-
*
|
|
3131
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
3340
|
+
getConversationSession(_conversationId: ConversationId): ConversationSession | undefined;
|
|
3166
3341
|
/**
|
|
3167
|
-
*
|
|
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
|
-
*
|
|
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
|
|
3352
|
+
protected get coChannel(): string;
|
|
3174
3353
|
/**
|
|
3175
|
-
*
|
|
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
|
-
|
|
3359
|
+
protected isOwnCoAddress(_address: string): boolean;
|
|
3178
3360
|
/**
|
|
3179
|
-
*
|
|
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
|
-
|
|
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
|
-
* -
|
|
3204
|
-
*
|
|
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 |
|
|
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
|
|
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
|
-
*
|
|
3346
|
-
*
|
|
3347
|
-
*
|
|
3348
|
-
*
|
|
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
|
|
3494
|
-
*
|
|
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
|
-
*
|
|
3501
|
-
*
|
|
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
|
-
*
|
|
3886
|
+
* Whether the author is TAC, judged from an already-fetched participant list.
|
|
3515
3887
|
*
|
|
3516
|
-
*
|
|
3517
|
-
*
|
|
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
|
-
*
|
|
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
|
|
3995
|
+
private resolveSession;
|
|
3532
3996
|
/**
|
|
3533
3997
|
* Handle new communication event (incoming message)
|
|
3534
3998
|
*/
|
|
3535
3999
|
private handleCommunicationCreated;
|
|
3536
4000
|
/**
|
|
3537
|
-
*
|
|
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(
|
|
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 →
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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(
|
|
4242
|
+
protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
|
|
4243
|
+
protected agentAddressFor(session: ConversationSession): ConversationAddress;
|
|
4244
|
+
private chatAddress;
|
|
3761
4245
|
/**
|
|
3762
|
-
*
|
|
4246
|
+
* Rebuild the session, recovering `channelId` from the participants.
|
|
3763
4247
|
*
|
|
3764
|
-
*
|
|
3765
|
-
*
|
|
3766
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
4065
|
-
*
|
|
4066
|
-
*
|
|
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
|
|
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
|
-
*
|
|
4540
|
-
*
|
|
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
|
-
|
|
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
|
|
4567
|
-
*
|
|
4568
|
-
* Voice channel processes
|
|
4569
|
-
*
|
|
4570
|
-
*
|
|
4571
|
-
*
|
|
4572
|
-
*
|
|
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(
|
|
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
|
|
4755
|
-
*
|
|
4756
|
-
* `onRecording`
|
|
4757
|
-
*
|
|
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
|
|
4773
|
-
*
|
|
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.
|
|
4875
|
-
* `TACConfig.voiceWebsocketPath`, or undefined when
|
|
4876
|
-
*
|
|
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.
|
|
5602
|
+
* `TACConfig.voiceCallbackDomain` + `TACConfig.voiceActionPath`.
|
|
4882
5603
|
*
|
|
4883
|
-
* Returns undefined if
|
|
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.
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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
|
-
*
|
|
6145
|
+
* Per-call session config overrides, minted by one Twilio request and
|
|
6146
|
+
* consumed when the call's WebSocket connects.
|
|
5378
6147
|
*
|
|
5379
|
-
*
|
|
5380
|
-
*
|
|
5381
|
-
*
|
|
5382
|
-
|
|
5383
|
-
|
|
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
|
-
|
|
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
|
|
5412
|
-
* from the session
|
|
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
|
|
5417
|
-
*
|
|
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
|
-
*
|
|
5430
|
-
*
|
|
5431
|
-
*
|
|
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
|
-
*
|
|
5434
|
-
* the call
|
|
5435
|
-
*
|
|
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
|
-
|
|
6209
|
+
protected withSessionConfigToken(host: VoiceTwiMLOptionsMediaStreams | undefined, perCall: VoiceTwiMLOptionsMediaStreams | undefined, token: string): VoiceTwiMLOptionsMediaStreams;
|
|
5438
6210
|
/**
|
|
5439
|
-
*
|
|
5440
|
-
*
|
|
5441
|
-
*
|
|
5442
|
-
*
|
|
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
|
|
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.
|
|
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
|
|
5470
|
-
*
|
|
5471
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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 };
|