twilio-agent-connect 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -3,6 +3,7 @@ export { z } from 'zod';
3
3
  import pino from 'pino';
4
4
  import { AxiosInstance } from 'axios';
5
5
  import { WebSocket } from 'ws';
6
+ import Twilio from 'twilio';
6
7
  import VoiceResponse from 'twilio/lib/twiml/VoiceResponse.js';
7
8
  import { CallListInstanceCreateOptions } from 'twilio/lib/rest/api/v2010/account/call.js';
8
9
  import { FastifyInstance, FastifyServerOptions } from 'fastify';
@@ -43,14 +44,17 @@ declare const CALL_EVENT_KINDS: readonly CallEventKind[];
43
44
  /**
44
45
  * TAC configuration schema
45
46
  */
46
- declare const TACConfigSchema: z.ZodObject<{
47
+ declare const TACConfigSchema: z.ZodPipe<z.ZodObject<{
47
48
  accountSid: z.ZodString;
48
49
  authToken: z.ZodString;
49
50
  apiKey: z.ZodString;
50
51
  apiSecret: z.ZodString;
51
- phoneNumber: z.ZodString;
52
+ phoneNumber: z.ZodOptional<z.ZodString>;
53
+ phoneNumbers: z.ZodOptional<z.ZodArray<z.ZodString>>;
52
54
  rcsSenderId: z.ZodOptional<z.ZodString>;
55
+ rcsSenderIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
53
56
  whatsappNumber: z.ZodOptional<z.ZodString>;
57
+ whatsappNumbers: z.ZodOptional<z.ZodArray<z.ZodString>>;
54
58
  memoryConfig: z.ZodPrefault<z.ZodObject<{
55
59
  traitGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
56
60
  observationsLimit: z.ZodDefault<z.ZodNumber>;
@@ -62,14 +66,82 @@ declare const TACConfigSchema: z.ZodObject<{
62
66
  }, z.core.$strip>>;
63
67
  conversationConfigurationId: z.ZodOptional<z.ZodString>;
64
68
  voicePublicDomain: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
65
- voiceWebsocketPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
66
- voiceActionPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
67
- voiceCallEventPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
69
+ voiceWebsocketPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
70
+ voiceActionPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
71
+ voiceCallEventPath: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
68
72
  cintelConfigurationId: z.ZodOptional<z.ZodString>;
69
73
  cintelSummaryOperatorSid: z.ZodOptional<z.ZodString>;
70
74
  region: z.ZodOptional<z.ZodString>;
71
75
  studioHandoffFlowSid: z.ZodOptional<z.ZodString>;
72
- }, z.core.$strip>;
76
+ }, z.core.$strip>, z.ZodTransform<{
77
+ phoneNumber: string;
78
+ phoneNumbers: string[];
79
+ rcsSenderId: string | undefined;
80
+ rcsSenderIds: string[];
81
+ whatsappNumber: string | undefined;
82
+ whatsappNumbers: string[];
83
+ accountSid: string;
84
+ authToken: string;
85
+ apiKey: string;
86
+ apiSecret: string;
87
+ memoryConfig: {
88
+ observationsLimit: number;
89
+ summariesLimit: number;
90
+ communicationsLimit: number;
91
+ relevanceThreshold: number;
92
+ phoneTraitGroup: string;
93
+ phoneTraitField: string;
94
+ traitGroups?: string[] | undefined;
95
+ };
96
+ voiceWebsocketPath: string;
97
+ voiceActionPath: string;
98
+ voiceCallEventPath: string;
99
+ conversationConfigurationId?: string | undefined;
100
+ voicePublicDomain?: string | undefined;
101
+ cintelConfigurationId?: string | undefined;
102
+ cintelSummaryOperatorSid?: string | undefined;
103
+ region?: string | undefined;
104
+ studioHandoffFlowSid?: string | undefined;
105
+ }, {
106
+ accountSid: string;
107
+ authToken: string;
108
+ apiKey: string;
109
+ apiSecret: string;
110
+ memoryConfig: {
111
+ observationsLimit: number;
112
+ summariesLimit: number;
113
+ communicationsLimit: number;
114
+ relevanceThreshold: number;
115
+ phoneTraitGroup: string;
116
+ phoneTraitField: string;
117
+ traitGroups?: string[] | undefined;
118
+ };
119
+ voiceWebsocketPath: string;
120
+ voiceActionPath: string;
121
+ voiceCallEventPath: string;
122
+ phoneNumber?: string | undefined;
123
+ phoneNumbers?: string[] | undefined;
124
+ rcsSenderId?: string | undefined;
125
+ rcsSenderIds?: string[] | undefined;
126
+ whatsappNumber?: string | undefined;
127
+ whatsappNumbers?: string[] | undefined;
128
+ conversationConfigurationId?: string | undefined;
129
+ voicePublicDomain?: string | undefined;
130
+ cintelConfigurationId?: string | undefined;
131
+ cintelSummaryOperatorSid?: string | undefined;
132
+ region?: string | undefined;
133
+ studioHandoffFlowSid?: string | undefined;
134
+ }>>;
135
+ /**
136
+ * Raw TAC configuration accepted by `new TACConfig()` and `TACOptions.config`.
137
+ * Fields the schema back-fills or defaults (e.g. `phoneNumbers`, `memoryConfig`)
138
+ * are optional here.
139
+ */
140
+ type TACConfigInput = z.input<typeof TACConfigSchema>;
141
+ /**
142
+ * Normalized TAC configuration produced by validating a {@link TACConfigInput}:
143
+ * defaults applied and each sender pair back-filled (default first, de-duplicated).
144
+ */
73
145
  type TACConfigData = z.infer<typeof TACConfigSchema>;
74
146
  /**
75
147
  * Environment variable mapping for configuration
@@ -80,8 +152,11 @@ declare const EnvironmentVariables: {
80
152
  readonly TWILIO_API_KEY: "TWILIO_API_KEY";
81
153
  readonly TWILIO_API_SECRET: "TWILIO_API_SECRET";
82
154
  readonly TWILIO_PHONE_NUMBER: "TWILIO_PHONE_NUMBER";
155
+ readonly TWILIO_PHONE_NUMBERS: "TWILIO_PHONE_NUMBERS";
83
156
  readonly TWILIO_RCS_SENDER_ID: "TWILIO_RCS_SENDER_ID";
157
+ readonly TWILIO_RCS_SENDER_IDS: "TWILIO_RCS_SENDER_IDS";
84
158
  readonly TWILIO_WHATSAPP_NUMBER: "TWILIO_WHATSAPP_NUMBER";
159
+ readonly TWILIO_WHATSAPP_NUMBERS: "TWILIO_WHATSAPP_NUMBERS";
85
160
  readonly TWILIO_MEMORY_PROFILE_TRAIT_GROUPS: "TWILIO_MEMORY_PROFILE_TRAIT_GROUPS";
86
161
  readonly TWILIO_MEMORY_OBSERVATIONS_LIMIT: "TWILIO_MEMORY_OBSERVATIONS_LIMIT";
87
162
  readonly TWILIO_MEMORY_SUMMARIES_LIMIT: "TWILIO_MEMORY_SUMMARIES_LIMIT";
@@ -1462,16 +1537,18 @@ declare const ConversationConfigurationSchema: z.ZodObject<{
1462
1537
  }, z.core.$strip>;
1463
1538
  type ConversationConfiguration = z.infer<typeof ConversationConfigurationSchema>;
1464
1539
  /**
1465
- * Options for initiating an outbound SMS conversation.
1540
+ * Options for initiating an outbound messaging conversation (SMS/RCS/WhatsApp).
1466
1541
  *
1467
- * The sender is always TAC's configured `config.phoneNumber`. Multi-sender
1468
- * deployments should run one TAC instance per sender so inbound webhook
1469
- * routing, memory scoping, and configuration stay in sync.
1542
+ * The sender defaults to the channel's configured default (`config.phoneNumber`
1543
+ * for SMS, `config.rcsSenderId` for RCS, `config.whatsappNumber` for WhatsApp).
1544
+ * Set `from` to send from any other configured sender for that channel
1545
+ * (`config.phoneNumbers` / `rcsSenderIds` / `whatsappNumbers`).
1470
1546
  */
1471
1547
  declare const InitiateMessagingConversationOptionsSchema: z.ZodObject<{
1472
1548
  to: z.ZodString;
1473
1549
  message: z.ZodString;
1474
1550
  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1551
+ from: z.ZodOptional<z.ZodString>;
1475
1552
  }, z.core.$strip>;
1476
1553
  type InitiateMessagingConversationOptions = z.infer<typeof InitiateMessagingConversationOptionsSchema>;
1477
1554
  /**
@@ -1737,7 +1814,8 @@ type InterruptMode = z.infer<typeof InterruptModeSchema>;
1737
1814
  *
1738
1815
  * Distinct from {@link LanguageAttributes} (the Twilio-SDK-shaped type used by
1739
1816
  * `connectConversationRelay`): this is the customization-facing model used in
1740
- * {@link TwiMLOptions}, mirroring the Python SDK's `LanguageConfig`.
1817
+ * {@link VoiceTwiMLOptionsConversationRelay}, mirroring the Python SDK's
1818
+ * `LanguageConfig`.
1741
1819
  */
1742
1820
  declare const LanguageConfigSchema: z.ZodObject<{
1743
1821
  code: z.ZodString;
@@ -1747,6 +1825,25 @@ declare const LanguageConfigSchema: z.ZodObject<{
1747
1825
  speechModel: z.ZodOptional<z.ZodString>;
1748
1826
  }, z.core.$strip>;
1749
1827
  type LanguageConfig = z.infer<typeof LanguageConfigSchema>;
1828
+ /**
1829
+ * Provider-agnostic base for a voice provider's inbound-call TwiML
1830
+ * customization options.
1831
+ *
1832
+ * Each provider answers the inbound-call webhook with its own TwiML shape
1833
+ * ({@link VoiceTwiMLOptionsConversationRelaySchema} for `<ConversationRelay>`,
1834
+ * {@link VoiceTwiMLOptionsMediaStreamsSchema} for `<Connect><Stream>`), so
1835
+ * `VoiceProvider.handleIncomingCall`'s
1836
+ * `hostTwimlOptions` is typed against this base rather than a specific
1837
+ * provider's options. It carries only what every provider shares: the
1838
+ * `<Connect action>` URL, the transport URL, and `<Parameter>` children.
1839
+ *
1840
+ * Mirrors the Python SDK's `VoiceTwiMLOptions`.
1841
+ */
1842
+ declare const VoiceTwiMLOptionsSchema: z.ZodObject<{
1843
+ customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1844
+ actionUrl: z.ZodOptional<z.ZodString>;
1845
+ websocketUrl: z.ZodOptional<z.ZodString>;
1846
+ }, z.core.$strict>;
1750
1847
  /**
1751
1848
  * Options for the TwiML inside `<ConversationRelay>` (plus the
1752
1849
  * `<Connect action>` URL).
@@ -1759,10 +1856,12 @@ type LanguageConfig = z.infer<typeof LanguageConfigSchema>;
1759
1856
  *
1760
1857
  * This is the customization-facing counterpart to {@link ConversationRelayConfig}
1761
1858
  * (which is the Twilio-SDK-shaped emit model and carries the required `url`).
1762
- * Mirrors the Python SDK's `TwiMLOptions`.
1859
+ * Mirrors the Python SDK's `VoiceTwiMLOptionsConversationRelay`.
1763
1860
  */
1764
- declare const TwiMLOptionsSchema: z.ZodObject<{
1861
+ declare const VoiceTwiMLOptionsConversationRelaySchema: z.ZodObject<{
1765
1862
  customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1863
+ actionUrl: z.ZodOptional<z.ZodString>;
1864
+ websocketUrl: z.ZodOptional<z.ZodString>;
1766
1865
  welcomeGreeting: z.ZodOptional<z.ZodString>;
1767
1866
  welcomeGreetingInterruptible: z.ZodOptional<z.ZodEnum<{
1768
1867
  any: "any";
@@ -1770,9 +1869,108 @@ declare const TwiMLOptionsSchema: z.ZodObject<{
1770
1869
  none: "none";
1771
1870
  dtmf: "dtmf";
1772
1871
  }>>;
1773
- actionUrl: z.ZodOptional<z.ZodString>;
1774
1872
  conversationConfiguration: z.ZodOptional<z.ZodString>;
1873
+ language: z.ZodOptional<z.ZodString>;
1874
+ ttsLanguage: z.ZodOptional<z.ZodString>;
1875
+ transcriptionLanguage: z.ZodOptional<z.ZodString>;
1876
+ voice: z.ZodOptional<z.ZodString>;
1877
+ ttsProvider: z.ZodOptional<z.ZodString>;
1878
+ transcriptionProvider: z.ZodOptional<z.ZodString>;
1879
+ speechModel: z.ZodOptional<z.ZodString>;
1880
+ elevenlabsTextNormalization: z.ZodOptional<z.ZodEnum<{
1881
+ on: "on";
1882
+ auto: "auto";
1883
+ off: "off";
1884
+ }>>;
1885
+ eotThreshold: z.ZodOptional<z.ZodNumber>;
1886
+ partialPrompts: z.ZodOptional<z.ZodBoolean>;
1887
+ deepgramSmartFormat: z.ZodOptional<z.ZodBoolean>;
1888
+ speechTimeout: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>>;
1889
+ interruptible: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
1890
+ any: "any";
1891
+ speech: "speech";
1892
+ none: "none";
1893
+ dtmf: "dtmf";
1894
+ }>, z.ZodBoolean]>>;
1895
+ interruptSensitivity: z.ZodOptional<z.ZodEnum<{
1896
+ low: "low";
1897
+ medium: "medium";
1898
+ high: "high";
1899
+ }>>;
1900
+ reportInputDuringAgentSpeech: z.ZodOptional<z.ZodEnum<{
1901
+ any: "any";
1902
+ speech: "speech";
1903
+ none: "none";
1904
+ dtmf: "dtmf";
1905
+ }>>;
1906
+ ignoreBackchannel: z.ZodOptional<z.ZodBoolean>;
1907
+ preemptible: z.ZodOptional<z.ZodBoolean>;
1908
+ dtmfDetection: z.ZodOptional<z.ZodBoolean>;
1909
+ hints: z.ZodOptional<z.ZodString>;
1910
+ events: z.ZodOptional<z.ZodString>;
1911
+ debug: z.ZodOptional<z.ZodString>;
1912
+ intelligenceService: z.ZodOptional<z.ZodString>;
1913
+ languages: z.ZodOptional<z.ZodArray<z.ZodObject<{
1914
+ code: z.ZodString;
1915
+ voice: z.ZodOptional<z.ZodString>;
1916
+ ttsProvider: z.ZodOptional<z.ZodString>;
1917
+ transcriptionProvider: z.ZodOptional<z.ZodString>;
1918
+ speechModel: z.ZodOptional<z.ZodString>;
1919
+ }, z.core.$strip>>>;
1920
+ extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>>;
1921
+ }, z.core.$strict>;
1922
+ type VoiceTwiMLOptions = z.infer<typeof VoiceTwiMLOptionsSchema>;
1923
+ type VoiceTwiMLOptionsConversationRelay = z.infer<typeof VoiceTwiMLOptionsConversationRelaySchema>;
1924
+ /**
1925
+ * Options for the TwiML inside `<Connect><Stream>`.
1926
+ *
1927
+ * Fields map to the attributes documented at
1928
+ * https://www.twilio.com/docs/voice/twiml/stream (the `<Stream>` verb) and
1929
+ * https://www.twilio.com/docs/voice/twiml/connect (the `<Connect>` verb it is
1930
+ * nested in). `track` is deliberately absent: a bidirectional `<Connect>`
1931
+ * stream only ever carries `inbound_track`, so it is not settable.
1932
+ *
1933
+ * Inherits `customParameters`, `actionUrl` and `websocketUrl` from the shared
1934
+ * base. Mirrors the Python SDK's `VoiceTwiMLOptionsMediaStreams`.
1935
+ */
1936
+ declare const VoiceTwiMLOptionsMediaStreamsSchema: z.ZodObject<{
1937
+ customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1938
+ actionUrl: z.ZodOptional<z.ZodString>;
1939
+ websocketUrl: z.ZodOptional<z.ZodString>;
1940
+ name: z.ZodOptional<z.ZodString>;
1941
+ statusCallback: z.ZodOptional<z.ZodString>;
1942
+ statusCallbackMethod: z.ZodOptional<z.ZodEnum<{
1943
+ POST: "POST";
1944
+ GET: "GET";
1945
+ }>>;
1946
+ actionMethod: z.ZodOptional<z.ZodEnum<{
1947
+ POST: "POST";
1948
+ GET: "GET";
1949
+ }>>;
1950
+ }, z.core.$strict>;
1951
+ type VoiceTwiMLOptionsMediaStreams = z.infer<typeof VoiceTwiMLOptionsMediaStreamsSchema>;
1952
+ /** @deprecated Use {@link VoiceTwiMLOptionsConversationRelay} instead. */
1953
+ type TwiMLOptions = VoiceTwiMLOptionsConversationRelay;
1954
+ /**
1955
+ * Unlike Python, this emits no runtime warning. It is a plain alias so that
1956
+ * `TwiMLOptionsSchema === VoiceTwiMLOptionsConversationRelaySchema`; wrapping it
1957
+ * in a warning proxy would break that identity, and callers commonly compare or
1958
+ * `.extend()` the schema.
1959
+ *
1960
+ * @deprecated Use {@link VoiceTwiMLOptionsConversationRelaySchema} instead.
1961
+ */
1962
+ declare const TwiMLOptionsSchema: z.ZodObject<{
1963
+ customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1964
+ actionUrl: z.ZodOptional<z.ZodString>;
1775
1965
  websocketUrl: z.ZodOptional<z.ZodString>;
1966
+ welcomeGreeting: z.ZodOptional<z.ZodString>;
1967
+ welcomeGreetingInterruptible: z.ZodOptional<z.ZodEnum<{
1968
+ any: "any";
1969
+ speech: "speech";
1970
+ none: "none";
1971
+ dtmf: "dtmf";
1972
+ }>>;
1973
+ conversationConfiguration: z.ZodOptional<z.ZodString>;
1776
1974
  language: z.ZodOptional<z.ZodString>;
1777
1975
  ttsLanguage: z.ZodOptional<z.ZodString>;
1778
1976
  transcriptionLanguage: z.ZodOptional<z.ZodString>;
@@ -1822,13 +2020,12 @@ declare const TwiMLOptionsSchema: z.ZodObject<{
1822
2020
  }, z.core.$strip>>>;
1823
2021
  extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>>;
1824
2022
  }, z.core.$strict>;
1825
- type TwiMLOptions = z.infer<typeof TwiMLOptionsSchema>;
1826
2023
  /**
1827
2024
  * Framework-neutral view of the Twilio TwiML webhook form.
1828
2025
  *
1829
2026
  * Populated by `TACServer` from the incoming Twilio webhook, then passed to a
1830
2027
  * customizer registered via `VoiceChannel.onInboundCallTwiml(...)` so the
1831
- * application can produce per-call {@link TwiMLOptions} overrides without
2028
+ * application can produce per-call {@link VoiceTwiMLOptions} overrides without
1832
2029
  * depending on Fastify types. Mirrors the Python SDK's `TwiMLRequest`.
1833
2030
  */
1834
2031
  declare const TwiMLRequestSchema: z.ZodObject<{
@@ -1887,6 +2084,12 @@ declare const ConversationRelayCallbackPayloadSchema: z.ZodObject<{
1887
2084
  SessionDuration: z.ZodOptional<z.ZodString>;
1888
2085
  }, z.core.$strip>;
1889
2086
  type ConversationRelayCallbackPayload = z.infer<typeof ConversationRelayCallbackPayloadSchema>;
2087
+ /** HTTP response a provider's out-of-band lifecycle webhook handler produces. */
2088
+ interface TwilioProviderCallbackResponse {
2089
+ status: number;
2090
+ content: string;
2091
+ contentType: string;
2092
+ }
1890
2093
  /**
1891
2094
  * A Twilio `statusCallback` webhook — call progress and disposition.
1892
2095
  *
@@ -2097,8 +2300,8 @@ declare function callOptionsToCreateParams(options: CallOptions): Record<string,
2097
2300
  /**
2098
2301
  * Options for initiating an outbound voice conversation.
2099
2302
  *
2100
- * The caller identity is always TAC's configured `config.phoneNumber`.
2101
- * Multi-number deployments should run one TAC instance per line.
2303
+ * The caller identity is TAC's configured `config.phoneNumber` by default, or
2304
+ * `from` when set to one of `config.phoneNumbers`.
2102
2305
  *
2103
2306
  * TwiML for the outbound call is built by merging per-field, highest precedence
2104
2307
  * first:
@@ -2114,6 +2317,11 @@ declare function callOptionsToCreateParams(options: CallOptions): Record<string,
2114
2317
  */
2115
2318
  interface InitiateVoiceConversationOptions {
2116
2319
  to: string;
2320
+ /**
2321
+ * Phone number to place the call from. Must be one of `config.phoneNumbers`.
2322
+ * When omitted, `config.phoneNumber` (the default sender) is used.
2323
+ */
2324
+ from?: string | undefined;
2117
2325
  /**
2118
2326
  * Public WebSocket URL for ConversationRelay (e.g. 'wss://your-domain.ngrok.app/ws').
2119
2327
  * Optional — defaults to the URL derived from `TACConfig.voicePublicDomain` +
@@ -2121,10 +2329,17 @@ interface InitiateVoiceConversationOptions {
2121
2329
  */
2122
2330
  websocketUrl?: string | undefined;
2123
2331
  /**
2124
- * Per-call overrides for the TwiML inside `<ConversationRelay>`. Merged over
2332
+ * Per-call overrides for the outbound TwiML. Merged over
2125
2333
  * `VoiceChannelConfig.defaultTwimlOptions` and TAC defaults.
2334
+ *
2335
+ * A union of the provider subtypes rather than the provider-agnostic base:
2336
+ * the base type carries only the three shared fields, so TypeScript's
2337
+ * excess-property check would reject a fresh object literal carrying any
2338
+ * provider-specific field. Each provider still parses this against its own
2339
+ * schema at the channel boundary, so passing the wrong subtype for the
2340
+ * configured provider fails at runtime.
2126
2341
  */
2127
- twimlOptions?: TwiMLOptions | undefined;
2342
+ twimlOptions?: VoiceTwiMLOptionsConversationRelay | VoiceTwiMLOptionsMediaStreams | undefined;
2128
2343
  /**
2129
2344
  * Parameters for Twilio's `calls.create()` — AMD, recording, status
2130
2345
  * callbacks, timeout (see {@link CallOptions}). Callback URLs auto-wire when
@@ -2132,7 +2347,96 @@ interface InitiateVoiceConversationOptions {
2132
2347
  */
2133
2348
  callOptions?: CallOptions | undefined;
2134
2349
  }
2350
+ /**
2351
+ * Validates outbound options for `ConversationRelayProvider`.
2352
+ *
2353
+ * Despite the union on {@link InitiateVoiceConversationOptions.twimlOptions},
2354
+ * this schema accepts only the ConversationRelay subtype — use
2355
+ * {@link InitiateVoiceConversationOptionsOpenAIRealtimeSchema} for
2356
+ * `<Connect><Stream>`.
2357
+ */
2135
2358
  declare const InitiateVoiceConversationOptionsSchema: z.ZodType<InitiateVoiceConversationOptions>;
2359
+ /**
2360
+ * Outbound options for `OpenAIRealtimeProvider`, adding a per-call
2361
+ * `sessionConfig` on top of {@link InitiateVoiceConversationOptionsSchema}.
2362
+ * Also narrows `twimlOptions` to {@link VoiceTwiMLOptionsMediaStreamsSchema}.
2363
+ *
2364
+ * Mirrors the Python SDK's `InitiateVoiceConversationOptionsOpenAIRealtime`.
2365
+ */
2366
+ declare const InitiateVoiceConversationOptionsOpenAIRealtimeSchema: z.ZodObject<{
2367
+ to: z.ZodString;
2368
+ from: z.ZodOptional<z.ZodString>;
2369
+ websocketUrl: z.ZodOptional<z.ZodURL>;
2370
+ callOptions: z.ZodOptional<z.ZodType<CallOptions, unknown, z.core.$ZodTypeInternals<CallOptions, unknown>>>;
2371
+ twimlOptions: z.ZodOptional<z.ZodObject<{
2372
+ customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
2373
+ actionUrl: z.ZodOptional<z.ZodString>;
2374
+ websocketUrl: z.ZodOptional<z.ZodString>;
2375
+ name: z.ZodOptional<z.ZodString>;
2376
+ statusCallback: z.ZodOptional<z.ZodString>;
2377
+ statusCallbackMethod: z.ZodOptional<z.ZodEnum<{
2378
+ POST: "POST";
2379
+ GET: "GET";
2380
+ }>>;
2381
+ actionMethod: z.ZodOptional<z.ZodEnum<{
2382
+ POST: "POST";
2383
+ GET: "GET";
2384
+ }>>;
2385
+ }, z.core.$strict>>;
2386
+ sessionConfig: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
2387
+ }, z.core.$strict>;
2388
+ type InitiateVoiceConversationOptionsOpenAIRealtime = z.infer<typeof InitiateVoiceConversationOptionsOpenAIRealtimeSchema>;
2389
+ /**
2390
+ * Outbound options for `GPTLiveProvider`, adding a per-call `sessionConfig` on
2391
+ * top of {@link InitiateVoiceConversationOptionsSchema}. Also narrows
2392
+ * `twimlOptions` to {@link VoiceTwiMLOptionsMediaStreamsSchema}.
2393
+ *
2394
+ * Mirrors the Python SDK's `InitiateVoiceConversationOptionsGPTLive`.
2395
+ */
2396
+ declare const InitiateVoiceConversationOptionsGPTLiveSchema: z.ZodObject<{
2397
+ to: z.ZodString;
2398
+ from: z.ZodOptional<z.ZodString>;
2399
+ websocketUrl: z.ZodOptional<z.ZodURL>;
2400
+ callOptions: z.ZodOptional<z.ZodType<CallOptions, unknown, z.core.$ZodTypeInternals<CallOptions, unknown>>>;
2401
+ twimlOptions: z.ZodOptional<z.ZodObject<{
2402
+ customParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
2403
+ actionUrl: z.ZodOptional<z.ZodString>;
2404
+ websocketUrl: z.ZodOptional<z.ZodString>;
2405
+ name: z.ZodOptional<z.ZodString>;
2406
+ statusCallback: z.ZodOptional<z.ZodString>;
2407
+ statusCallbackMethod: z.ZodOptional<z.ZodEnum<{
2408
+ POST: "POST";
2409
+ GET: "GET";
2410
+ }>>;
2411
+ actionMethod: z.ZodOptional<z.ZodEnum<{
2412
+ POST: "POST";
2413
+ GET: "GET";
2414
+ }>>;
2415
+ }, z.core.$strict>>;
2416
+ sessionConfig: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
2417
+ }, z.core.$strict>;
2418
+ type InitiateVoiceConversationOptionsGPTLive = z.infer<typeof InitiateVoiceConversationOptionsGPTLiveSchema>;
2419
+
2420
+ /**
2421
+ * The `start` field of Twilio's Media Stream `start` event.
2422
+ *
2423
+ * This is an inbound, read-only message Twilio pushes over the
2424
+ * `<Connect><Stream>` WebSocket, so unlike the outbound TwiML options it
2425
+ * carries no snake_case alias layer — the wire names are parsed directly.
2426
+ *
2427
+ * Mirrors the Python SDK's `StreamStartMessage`. Python exposes a
2428
+ * `conversation_id` property aliasing `call_sid`; here callers read `callSid`
2429
+ * directly.
2430
+ *
2431
+ * @see https://www.twilio.com/docs/voice/media-streams/websocket-messages
2432
+ */
2433
+ declare const StreamStartMessageSchema: z.ZodObject<{
2434
+ streamSid: z.ZodString;
2435
+ callSid: z.ZodString;
2436
+ mediaFormat: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
2437
+ customParameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
2438
+ }, z.core.$strip>;
2439
+ type StreamStartMessage = z.infer<typeof StreamStartMessageSchema>;
2136
2440
 
2137
2441
  /**
2138
2442
  * Structured payload generated during a handoff.
@@ -2231,6 +2535,33 @@ declare const AnthropicToolSchema: z.ZodObject<{
2231
2535
  }, z.core.$strip>;
2232
2536
  }, z.core.$strip>;
2233
2537
  type AnthropicTool = z.infer<typeof AnthropicToolSchema>;
2538
+ /**
2539
+ * OpenAI Realtime tool format.
2540
+ *
2541
+ * Realtime's `session.tools` expects the fields flat on the tool object,
2542
+ * unlike Chat Completions ({@link OpenAIToolSchema}), which nests them under a
2543
+ * `function` key.
2544
+ */
2545
+ declare const OpenAIRealtimeToolSchema: z.ZodObject<{
2546
+ type: z.ZodLiteral<"function">;
2547
+ name: z.ZodString;
2548
+ description: z.ZodString;
2549
+ parameters: z.ZodObject<{
2550
+ type: z.ZodEnum<{
2551
+ string: "string";
2552
+ number: "number";
2553
+ boolean: "boolean";
2554
+ object: "object";
2555
+ array: "array";
2556
+ }>;
2557
+ properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
2558
+ required: z.ZodOptional<z.ZodArray<z.ZodString>>;
2559
+ items: z.ZodOptional<z.ZodAny>;
2560
+ enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
2561
+ description: z.ZodOptional<z.ZodString>;
2562
+ }, z.core.$strip>;
2563
+ }, z.core.$strip>;
2564
+ type OpenAIRealtimeTool = z.infer<typeof OpenAIRealtimeToolSchema>;
2234
2565
  /**
2235
2566
  * Tool execution context
2236
2567
  */
@@ -2460,9 +2791,24 @@ declare class TACConfig {
2460
2791
  readonly authToken: string;
2461
2792
  readonly apiKey: string;
2462
2793
  readonly apiSecret: string;
2794
+ /**
2795
+ * Default Twilio phone number for Voice and SMS — the sender used for
2796
+ * outbound when a call does not specify `from`. Always populated and always a
2797
+ * member of {@link phoneNumbers}.
2798
+ */
2463
2799
  readonly phoneNumber: string;
2800
+ /**
2801
+ * Full set of Twilio phone numbers this instance serves for Voice and SMS
2802
+ * (the inbound allowlist). Always includes {@link phoneNumber} as the first,
2803
+ * default sender.
2804
+ */
2805
+ readonly phoneNumbers: string[];
2464
2806
  readonly rcsSenderId?: string;
2807
+ /** Full set of RCS Sender IDs this instance serves; the default is first. */
2808
+ readonly rcsSenderIds: string[];
2465
2809
  readonly whatsappNumber?: string;
2810
+ /** Full set of WhatsApp numbers this instance serves; the default is first. */
2811
+ readonly whatsappNumbers: string[];
2466
2812
  readonly memoryConfig: TACConfigData['memoryConfig'];
2467
2813
  readonly conversationConfigurationId?: string;
2468
2814
  readonly voicePublicDomain?: string;
@@ -2484,7 +2830,7 @@ declare class TACConfig {
2484
2830
  * from this SID.
2485
2831
  */
2486
2832
  readonly studioHandoffFlowSid?: string;
2487
- constructor(data: TACConfigData | z.input<typeof TACConfigSchema>);
2833
+ constructor(data: TACConfigInput);
2488
2834
  /**
2489
2835
  * Create TACConfig from environment variables.
2490
2836
  *
@@ -2493,10 +2839,13 @@ declare class TACConfig {
2493
2839
  * - TWILIO_AUTH_TOKEN: Twilio Auth Token for API authentication
2494
2840
  * - TWILIO_API_KEY: Twilio API Key SID (starts with SK)
2495
2841
  * - TWILIO_API_SECRET: Twilio API Secret for API Key authentication
2496
- * - TWILIO_PHONE_NUMBER: Phone number for voice and SMS channels
2842
+ * - TWILIO_PHONE_NUMBER and/or TWILIO_PHONE_NUMBERS: at least one is required.
2843
+ * Phone number(s) for voice and SMS channels — see **Multi-Value Senders** below.
2497
2844
  *
2498
2845
  * Optional environment variables:
2499
- * - TWILIO_WHATSAPP_NUMBER: WhatsApp number for WhatsApp channel (e.g., 'whatsapp:+1234567890')
2846
+ * - TWILIO_WHATSAPP_NUMBER / TWILIO_WHATSAPP_NUMBERS: WhatsApp number(s) for the
2847
+ * WhatsApp channel (e.g., 'whatsapp:+1234567890')
2848
+ * - TWILIO_RCS_SENDER_ID / TWILIO_RCS_SENDER_IDS: RCS Sender ID(s) for the RCS channel
2500
2849
  * - TWILIO_CONVERSATION_CONFIGURATION_ID: Conversation Orchestrator configuration ID (enables orchestrated mode)
2501
2850
  * - 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')
2502
2851
  * - TWILIO_VOICE_WEBSOCKET_PATH: Path for the voice WebSocket (default: /ws)
@@ -2504,7 +2853,16 @@ declare class TACConfig {
2504
2853
  * - TWILIO_VOICE_CALL_EVENT_PATH: Base path for the call-event callbacks — status, async AMD, recording (default: /twilio/call-events)
2505
2854
  * - TWILIO_REGION: Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`)
2506
2855
  * - TWILIO_STUDIO_HANDOFF_FLOW_SID: Studio Flow SID used by createStudioHandoffTool for human handoff
2507
- * - TWILIO_RCS_SENDER_ID: RCS Sender ID for the RCS channel
2856
+ *
2857
+ * Multi-Value Senders:
2858
+ * - Each singular env var (TWILIO_PHONE_NUMBER, TWILIO_RCS_SENDER_ID,
2859
+ * TWILIO_WHATSAPP_NUMBER) pairs with a plural, comma-separated one
2860
+ * (TWILIO_PHONE_NUMBERS, TWILIO_RCS_SENDER_IDS, TWILIO_WHATSAPP_NUMBERS),
2861
+ * e.g. `TWILIO_PHONE_NUMBERS=+1555,+1444`. Whichever side is set back-fills
2862
+ * the other: the singular becomes the default sender and the plural the full
2863
+ * allowlist. Entries are whitespace-trimmed and de-duplicated, with the
2864
+ * default kept first. `phoneNumber` requires at least one of the two; the RCS
2865
+ * and WhatsApp pairs stay optional.
2508
2866
  *
2509
2867
  * Memory Configuration (defaults defined in TwilioMemoryConfigSchema):
2510
2868
  * - TWILIO_MEMORY_PROFILE_TRAIT_GROUPS: Trait groups to include (comma-separated, e.g., "Contact,Preferences")
@@ -2899,6 +3257,17 @@ declare abstract class BaseChannel {
2899
3257
  * Get the channel type (implemented by subclasses)
2900
3258
  */
2901
3259
  abstract get channelType(): ChannelType;
3260
+ /**
3261
+ * Resolve the outbound sender address for this channel.
3262
+ *
3263
+ * `requested` (the caller's `options.from`) wins when it is one of the
3264
+ * channel's configured senders; otherwise throws. When omitted, the channel
3265
+ * default is used.
3266
+ */
3267
+ protected resolveOutboundFrom(requested: string | undefined, options: {
3268
+ allowlist: string[];
3269
+ default: string | undefined;
3270
+ }): string;
2902
3271
  /**
2903
3272
  * Register event callbacks
2904
3273
  */
@@ -3024,7 +3393,7 @@ declare abstract class BaseChannel {
3024
3393
  }
3025
3394
 
3026
3395
  interface TACOptions {
3027
- config?: TACConfig | TACConfigData;
3396
+ config?: TACConfig | TACConfigInput;
3028
3397
  logger?: Logger;
3029
3398
  }
3030
3399
  /**
@@ -3040,10 +3409,24 @@ type MessageReadyCallback = (params: {
3040
3409
  channel: ChannelType;
3041
3410
  abortSignal?: AbortSignal;
3042
3411
  }) => Promise<string | null | void> | string | null | void;
3412
+ /**
3413
+ * Callback registered with {@link TAC.onInterrupt}, invoked when the caller
3414
+ * interrupts the agent on a voice call.
3415
+ */
3043
3416
  type InterruptCallback = (params: {
3417
+ /** The interrupted conversation. */
3044
3418
  conversationId: ConversationId;
3419
+ /**
3420
+ * Text the agent had spoken when interrupted. `undefined` if
3421
+ * ConversationRelay doesn't report it.
3422
+ */
3045
3423
  utteranceUntilInterrupt: string | undefined;
3424
+ /**
3425
+ * How long the agent had been speaking, in milliseconds. `undefined` if
3426
+ * ConversationRelay doesn't report it.
3427
+ */
3046
3428
  durationUntilInterruptMs: number | undefined;
3429
+ /** The live session for the call. */
3047
3430
  session: ConversationSession;
3048
3431
  }) => Promise<void> | void;
3049
3432
  type ConversationEndedCallback = (params: {
@@ -3071,7 +3454,16 @@ declare class TAC {
3071
3454
  private constructor();
3072
3455
  static create(options?: TACOptions): Promise<TAC>;
3073
3456
  /**
3074
- * Register a channel with the framework
3457
+ * Register a channel with the framework, routing its inbound messages to the
3458
+ * {@link TAC.onMessageReady} callback and shutting it down with {@link TAC.shutdown}.
3459
+ *
3460
+ * `TACServer` registers the channels passed to it (`voiceChannel` /
3461
+ * `messagingChannels`), so you only need this when wiring channels into your
3462
+ * own web framework instead of `TACServer`.
3463
+ *
3464
+ * Only one channel per type is registered: registering a different instance
3465
+ * of the same type shuts down and replaces the existing one. Registering the
3466
+ * same instance again is a no-op.
3075
3467
  */
3076
3468
  registerChannel(channel: BaseChannel): void;
3077
3469
  /**
@@ -3088,7 +3480,24 @@ declare class TAC {
3088
3480
  */
3089
3481
  onMessageReady(callback: MessageReadyCallback): void;
3090
3482
  /**
3091
- * Register callback for when user interrupts (voice channel)
3483
+ * Register callback invoked when the caller interrupts the agent on a voice call.
3484
+ *
3485
+ * Currently fired by the ConversationRelay voice provider. The callback receives
3486
+ * `conversationId`, the call's `session`, `utteranceUntilInterrupt` (the text the
3487
+ * agent had spoken when interrupted) and `durationUntilInterruptMs` (how long it
3488
+ * had been speaking); either of the last two may be `undefined` if
3489
+ * ConversationRelay doesn't report it. Errors thrown by the callback are logged,
3490
+ * not rethrown.
3491
+ *
3492
+ * @example
3493
+ * ```typescript
3494
+ * tac.onInterrupt(({ conversationId, utteranceUntilInterrupt, durationUntilInterruptMs }) => {
3495
+ * console.log(
3496
+ * `${conversationId} interrupted after ${durationUntilInterruptMs} ms: ` +
3497
+ * JSON.stringify(utteranceUntilInterrupt)
3498
+ * );
3499
+ * });
3500
+ * ```
3092
3501
  */
3093
3502
  onInterrupt(callback: InterruptCallback): void;
3094
3503
  /**
@@ -3182,6 +3591,22 @@ declare class TAC {
3182
3591
  shutdown(): void;
3183
3592
  }
3184
3593
 
3594
+ type EventProperties = {
3595
+ account_sid: string;
3596
+ } & Record<string, unknown>;
3597
+ /**
3598
+ * Record a telemetry event. Never throws.
3599
+ *
3600
+ * @internal
3601
+ */
3602
+ declare function trackEvent(event: string, properties: EventProperties): void;
3603
+ /**
3604
+ * Flush pending events and close the client. Called by `TAC.shutdown()`.
3605
+ *
3606
+ * @internal
3607
+ */
3608
+ declare function shutdownAnalytics(): Promise<void>;
3609
+
3185
3610
  /**
3186
3611
  * Messaging channel configuration options.
3187
3612
  * Alias for BaseChannelOptions that can be extended by specific channel implementations.
@@ -3215,6 +3640,12 @@ interface MessagingChannelEvents extends BaseChannelEvents {
3215
3640
  * promote a channel-matching UNKNOWN participant (not owning the agent
3216
3641
  * address) to CUSTOMER. Set `false` for channels where the customer is
3217
3642
  * identified author-driven (e.g. chat).
3643
+ * - `deriveInboundAgentFromRecipients`: if `true` (default), the inbound agent
3644
+ * address is derived from the webhook's recipient (which of TAC's configured
3645
+ * numbers was messaged), validated against the channel's allowlist. `true` for
3646
+ * phone-like channels (SMS, RCS, WhatsApp). Set `false` for channels where the
3647
+ * agent is a single identity rather than a number set (e.g. chat), which keeps
3648
+ * the default-address path instead.
3218
3649
  */
3219
3650
  declare abstract class MessagingChannel extends BaseChannel {
3220
3651
  protected readonly conversationClient: ConversationClient;
@@ -3224,10 +3655,25 @@ declare abstract class MessagingChannel extends BaseChannel {
3224
3655
  * participant to CUSTOMER. Subclasses override to opt out (e.g. chat).
3225
3656
  */
3226
3657
  protected reconcileCustomerType: boolean;
3658
+ /**
3659
+ * Phone-like channels derive the agent address from the inbound webhook's
3660
+ * recipient (which of TAC's numbers was messaged). Chat uses a single identity
3661
+ * and opts out, keeping the default-address path.
3662
+ */
3663
+ protected deriveInboundAgentFromRecipients: boolean;
3664
+ /**
3665
+ * The uppercase Conversation Orchestrator channel name for this channel (e.g.
3666
+ * `"SMS"`, `"RCS"`), used to filter webhook recipients and participant
3667
+ * addresses. Derived from {@link channelType}.
3668
+ */
3669
+ protected getChannelName(): ParticipantAddressType;
3227
3670
  constructor(tac: TAC, config?: MessagingChannelConfig);
3228
3671
  /**
3229
- * Fast-path check: is the author address this channel's default agent address?
3230
- * (e.g., config.phoneNumber for SMS, agentAddress for Chat)
3672
+ * Fast-path check: is the author address one of this channel's configured agent addresses?
3673
+ *
3674
+ * Checks the channel's full sender allowlist, not just the default sender:
3675
+ * `config.phoneNumbers` for SMS, `config.rcsSenderIds` for RCS,
3676
+ * `config.whatsappNumbers` for WhatsApp, and `agentAddress` for Chat.
3231
3677
  */
3232
3678
  protected abstract isDefaultAgentAddress(authorAddress: string): boolean;
3233
3679
  /**
@@ -3238,6 +3684,14 @@ declare abstract class MessagingChannel extends BaseChannel {
3238
3684
  * per-conversation channelId) to build the address.
3239
3685
  */
3240
3686
  protected abstract getAgentAddress(conversationId: ConversationId): ConversationAddress;
3687
+ /**
3688
+ * Report a delivered response.
3689
+ *
3690
+ * Each channel calls this from its own `sendResponse` rather than the base
3691
+ * wrapping the call: `sendResponse` is the public extension point, so making
3692
+ * it a template method would break subclasses defined outside this package.
3693
+ */
3694
+ protected trackResponseSent(conversationId: ConversationId): void;
3241
3695
  /**
3242
3696
  * Check if a message is from the bot itself (2-tier).
3243
3697
  *
@@ -3298,12 +3752,23 @@ declare abstract class MessagingChannel extends BaseChannel {
3298
3752
  * (via `session.authorInfo.participantId`), so promoting some other
3299
3753
  * `UNKNOWN` CHAT participant could pick the wrong recipient.
3300
3754
  *
3755
+ * @param agentAddress - The agent address for this conversation, normally
3756
+ * derived from the inbound webhook's recipient. When omitted, it is resolved
3757
+ * from a participant scan (phone-like channels) or the channel default.
3301
3758
  * @returns `[agent, customerOrNull]` on success. `customer` is `null` when
3302
3759
  * `reconcileCustomerType` is `false`. `null` overall when either the agent
3303
3760
  * or the customer cannot be resolved — the caller treats `null` as a hard
3304
3761
  * stop and skips the message-ready callback.
3305
3762
  */
3306
- protected reconcileParticipants(conversationId: ConversationId): Promise<[ConversationParticipant, ConversationParticipant | null] | null>;
3763
+ protected reconcileParticipants(conversationId: ConversationId, agentAddress?: ConversationAddress): Promise<[ConversationParticipant, ConversationParticipant | null] | null>;
3764
+ /**
3765
+ * Resolve the agent address when the inbound webhook carried no recipient.
3766
+ *
3767
+ * Scans the conversation's participants for any of TAC's configured addresses
3768
+ * on this channel; falls back to the channel default when none is present.
3769
+ * Defensive path — the primary source is the webhook.
3770
+ */
3771
+ protected fallbackAgentAddress(conversationId: ConversationId, participants: ConversationParticipant[], channel: ParticipantAddressType): ConversationAddress;
3307
3772
  /**
3308
3773
  * Find or mint a Conversation Memory profile for a customer being promoted from UNKNOWN.
3309
3774
  *
@@ -3381,7 +3846,8 @@ declare class SMSChannel extends MessagingChannel {
3381
3846
  *
3382
3847
  * Creates a conversation via Conversation Orchestrator, adds customer and
3383
3848
  * agent participants, then sends the initial message via the Actions API.
3384
- * The sender is always `config.phoneNumber`.
3849
+ * Uses `options.from` when provided (must be one of the configured phone
3850
+ * numbers), otherwise falls back to the default `config.phoneNumber`.
3385
3851
  */
3386
3852
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3387
3853
  }
@@ -3414,7 +3880,8 @@ declare class RCSChannel extends MessagingChannel {
3414
3880
  *
3415
3881
  * Creates a conversation via Conversation Orchestrator, adds customer and
3416
3882
  * agent participants, then sends the initial message via the Actions API.
3417
- * The sender is always `config.rcsSenderId`.
3883
+ * Uses `options.from` when provided (must be one of the configured RCS
3884
+ * senders), otherwise falls back to the default `config.rcsSenderId`.
3418
3885
  */
3419
3886
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3420
3887
  }
@@ -3429,6 +3896,7 @@ declare class RCSChannel extends MessagingChannel {
3429
3896
  * (via TWILIO_WHATSAPP_NUMBER). Address format: whatsapp:+1234567890
3430
3897
  */
3431
3898
  declare class WhatsAppChannel extends MessagingChannel {
3899
+ constructor(tac: TAC, config?: MessagingChannelConfig);
3432
3900
  get channelType(): ChannelType;
3433
3901
  protected isDefaultAgentAddress(authorAddress: string): boolean;
3434
3902
  protected getAgentAddress(_conversationId: ConversationId): ConversationAddress;
@@ -3447,7 +3915,8 @@ declare class WhatsAppChannel extends MessagingChannel {
3447
3915
  *
3448
3916
  * Creates a conversation via Conversation Orchestrator, adds customer and
3449
3917
  * agent participants, then sends the initial message via the Actions API.
3450
- * The sender is always `config.whatsappNumber`.
3918
+ * Uses `options.from` when provided (must be one of the configured WhatsApp
3919
+ * numbers), otherwise falls back to the default `config.whatsappNumber`.
3451
3920
  */
3452
3921
  initiateOutboundConversation(options: InitiateMessagingConversationOptions): Promise<InitiateConversationResult>;
3453
3922
  }
@@ -3482,6 +3951,7 @@ interface ChatChannelConfig extends MessagingChannelConfig {
3482
3951
  declare class ChatChannel extends MessagingChannel {
3483
3952
  private readonly agentAddress;
3484
3953
  protected reconcileCustomerType: boolean;
3954
+ protected deriveInboundAgentFromRecipients: boolean;
3485
3955
  constructor(tac: TAC, config?: ChatChannelConfig);
3486
3956
  get channelType(): ChannelType;
3487
3957
  protected isDefaultAgentAddress(authorAddress: string): boolean;
@@ -3507,272 +3977,272 @@ declare class ChatChannel extends MessagingChannel {
3507
3977
  }
3508
3978
 
3509
3979
  /**
3510
- * Configuration for the Voice channel.
3980
+ * Base class for a {@link VoiceChannel}'s real-time media provider.
3511
3981
  *
3512
- * `defaultTwimlOptions` is one of several TwiML layers that merge per-field;
3513
- * see `handleIncomingCall` (inbound) and `initiateOutboundConversation`
3514
- * (outbound) for the full precedence order.
3515
- */
3516
- interface VoiceChannelConfig extends BaseChannelOptions {
3982
+ * Holds the owning `channel` (Calls API lifecycle, conversation bookkeeping,
3983
+ * `TAC`). Every method here has a default that either declines the capability
3984
+ * or does nothing, so a provider only implements the transport it actually
3985
+ * supports — ConversationRelay serves inbound TwiML and a WebSocket, while a
3986
+ * provider with no inbound story simply inherits the refusal.
3987
+ */
3988
+ declare class VoiceProvider {
3989
+ /** The `VoiceChannel` that owns this provider. */
3990
+ readonly channel: VoiceChannel;
3991
+ /** Logger named after the concrete provider class. */
3992
+ protected readonly logger: Logger;
3993
+ constructor(channel: VoiceChannel);
3517
3994
  /**
3518
- * Static `TwiMLOptions` applied to every call (inbound and outbound).
3519
- * Controls the TwiML inside `<ConversationRelay>` — voice, language,
3520
- * transcription provider, welcomeGreeting, `<Language>` children, etc. Use
3521
- * this when the same ConversationRelay configuration is correct for every call.
3995
+ * Stable snake_case identifier for this provider, reported on voice
3996
+ * telemetry events so emissions from different transports are
3997
+ * distinguishable. Built-in providers override it; a provider defined outside
3998
+ * the SDK inherits `"custom"`.
3522
3999
  *
3523
- * Per-call inbound customization is registered via
3524
- * `VoiceChannel.onInboundCallTwiml(...)` (not on this config).
4000
+ * @internal
4001
+ */
4002
+ get providerId(): string;
4003
+ /**
4004
+ * Channel name identifier, e.g. `"VOICE"`.
3525
4005
  *
3526
- * Note: `customParameters` and `languages` replace wholesale when a
3527
- * higher-priority layer sets them.
4006
+ * A label for this provider's transport; it does not change how
4007
+ * `VoiceChannel` reports its `ChannelType`.
3528
4008
  */
3529
- defaultTwimlOptions?: TwiMLOptions;
4009
+ get channelName(): string;
3530
4010
  /**
3531
- * Static {@link CallOptions} applied to every outbound call — the
3532
- * `calls.create` parameters, including the call-event callback URLs. This is
3533
- * the layer to use for a custom server or non-default routes: URLs set here
3534
- * override the ones TAC would derive from `voicePublicDomain` +
3535
- * `voiceCallEventPath`.
4011
+ * Build the response for an inbound call. Default: not supported.
4012
+ *
4013
+ * @param _twimlRequest - Parsed Twilio webhook fields for the inbound call.
4014
+ * @param _options - Additional per-call inputs.
4015
+ * @param _options.hostTwimlOptions - Per-call TwiML supplied by a custom
4016
+ * in-process host.
3536
4017
  */
3537
- defaultCallOptions?: CallOptions;
4018
+ handleIncomingCall(_twimlRequest?: TwiMLRequest, _options?: {
4019
+ hostTwimlOptions?: VoiceTwiMLOptions;
4020
+ }): Promise<string>;
4021
+ /**
4022
+ * Handle this provider's own out-of-band lifecycle webhook, if it has one.
4023
+ *
4024
+ * Not every provider has an equivalent — Twilio's ConversationRelay posts to
4025
+ * `<Connect action=...>` when the session ends (`ConversationRelayProvider`
4026
+ * uses this as a WebSocket-disconnect backup); Media Streams instead has its
4027
+ * own independent `statusCallback` (`stream-started` / `stream-stopped` /
4028
+ * `stream-error`), which is purely informational and doesn't gate call flow.
4029
+ * Default acknowledges with an empty 200 for providers with nothing to do
4030
+ * here.
4031
+ */
4032
+ handleTwilioProviderCallback(_payload: Record<string, unknown>): Promise<TwilioProviderCallbackResponse>;
4033
+ /**
4034
+ * Drive one WebSocket connection from accept to disconnect.
4035
+ *
4036
+ * Implementations may be synchronous or asynchronous: a provider that only
4037
+ * attaches event handlers can return `void`, while one that awaits an
4038
+ * upstream handshake before serving traffic returns a `Promise<void>`. The
4039
+ * owning `VoiceChannel` is responsible for handling a returned promise's
4040
+ * rejection, so an async override never produces an unhandled rejection.
4041
+ */
4042
+ handleWebSocket(_websocket: WebSocket): void | Promise<void>;
4043
+ /** Place an outbound call. Default: not supported. */
4044
+ initiateOutboundConversation(_options: InitiateVoiceConversationOptions): Promise<InitiateVoiceConversationResult>;
4045
+ /** Send a text response back through this provider's transport, if supported. */
4046
+ sendResponse(_conversationId: ConversationId, _message: string, _metadata?: Record<string, unknown>): Promise<void>;
4047
+ /**
4048
+ * Stream a text response back through this provider's transport, token by
4049
+ * token, if supported. Default: not supported.
4050
+ *
4051
+ * @param _conversationId - Conversation whose transport receives the tokens.
4052
+ * @param _stream - Async iterable of text chunks to relay as they arrive.
4053
+ * @param _options - Additional per-call inputs.
4054
+ * @param _options.signal - Aborts the stream mid-flight, e.g. when the caller
4055
+ * interrupts.
4056
+ * @returns The accumulated response text.
4057
+ */
4058
+ sendStreamingResponse(_conversationId: ConversationId, _stream: AsyncIterable<string>, _options?: {
4059
+ signal?: AbortSignal;
4060
+ }): Promise<string>;
4061
+ /** Return the Twilio-facing WebSocket for a conversation, if tracked. */
4062
+ getWebSocket(_conversationId: ConversationId): WebSocket | null;
4063
+ /**
4064
+ * Drop this provider's transport state on channel shutdown.
4065
+ *
4066
+ * Called by {@link VoiceChannel.shutdown} before the channel clears its own
4067
+ * conversation bookkeeping. Default no-op — providers override this to drop
4068
+ * whatever transport state they track. Live WebSocket connections are owned
4069
+ * and closed by the server, so an override only clears in-process tracking.
4070
+ */
4071
+ shutdown(): void;
4072
+ /**
4073
+ * Set callback URLs on `callParams` for every registered call-event handler.
4074
+ *
4075
+ * A URL is derived only when its handler is registered — an unwanted
4076
+ * call-event URL would otherwise surface as silent 11200 alerts for a
4077
+ * feature nobody asked for. If TAC isn't serving these routes, set the URLs
4078
+ * explicitly via `CallOptions` (or the provider config's default call
4079
+ * options, where available). An explicit URL from either options layer is
4080
+ * never overwritten.
4081
+ */
4082
+ protected applyCallEventCallbacks(callParams: Record<string, unknown>): Record<string, unknown>;
4083
+ /**
4084
+ * Resolve the outbound caller ID for a voice call.
4085
+ *
4086
+ * Validates `requested` against `config.phoneNumbers`, defaulting to
4087
+ * `config.phoneNumber` — the same rule messaging channels apply via
4088
+ * `resolveOutboundSender`.
4089
+ */
4090
+ protected resolveFromNumber(requested: string | undefined): string;
3538
4091
  }
3539
4092
  /**
3540
- * Callback that produces per-call overrides for the TwiML inside
3541
- * `<ConversationRelay>` on inbound calls. Receives a framework-neutral
3542
- * {@link TwiMLRequest} and returns {@link TwiMLOptions}.
4093
+ * Base configuration for a {@link VoiceChannel}'s real-time media provider.
4094
+ *
4095
+ * Subclasses add their provider's own settings and implement
4096
+ * {@link VoiceProviderConfig.createProvider} to build the provider they
4097
+ * configure.
3543
4098
  */
3544
- type InboundCallTwimlHandler = (req: TwiMLRequest) => Promise<TwiMLOptions>;
3545
- /** Handler for Twilio `statusCallback` webhooks. */
3546
- type CallStatusHandler = (event: CallStatusEvent) => Promise<void> | void;
3547
- /** Handler for Twilio `asyncAmdStatusCallback` webhooks. */
3548
- type AmdHandler = (event: AmdEvent) => Promise<void> | void;
3549
- /** Handler for Twilio `recordingStatusCallback` webhooks. */
3550
- type RecordingHandler = (event: RecordingEvent) => Promise<void> | void;
3551
- /** One ConversationRelay keypress, as delivered to a {@link DtmfHandler}. */
3552
- interface DtmfEvent {
4099
+ declare class VoiceProviderConfig {
4100
+ /** Memory retrieval mode for this channel. Defaults to `'never'`. */
4101
+ memoryMode: MemoryMode;
3553
4102
  /**
3554
- * Undefined only when the keypress beat conversation setup: `dtmf` before
3555
- * ConversationRelay's `setup`, or an orchestrated-mode lookup that failed.
4103
+ * The {@link BaseChannelOptions} this config was constructed with, retained
4104
+ * verbatim so `VoiceChannel` can hand them to `BaseChannel`.
4105
+ *
4106
+ * A provider config carries channel-level options (`dedupCapacity` and
4107
+ * friends) alongside its own provider settings; without this they would be
4108
+ * dropped on the config path while still applying on the plain-object path,
4109
+ * which is the same channel configured two ways.
4110
+ *
4111
+ * @internal
3556
4112
  */
3557
- conversationId: ConversationId | undefined;
3558
- /** Undefined only before ConversationRelay's `setup` message. */
3559
- callSid: string | undefined;
3560
- /** The key pressed: `0`-`9`, `*`, `#`, or `A`-`D`. */
3561
- digit: string;
3562
- /** Present whenever `conversationId` is. */
3563
- session?: ConversationSession;
4113
+ readonly channelOptions: BaseChannelOptions;
4114
+ constructor(options?: BaseChannelOptions);
4115
+ /**
4116
+ * Build the {@link VoiceProvider} this config configures.
4117
+ *
4118
+ * @param _channel - The owning `VoiceChannel`.
4119
+ * @param _tacConfig - `TACConfig` — providers that talk TwiML need it to
4120
+ * derive default URLs (`voicePublicDomain` etc.).
4121
+ */
4122
+ createProvider(_channel: VoiceChannel, _tacConfig: TACConfig): VoiceProvider;
3564
4123
  }
3565
- /** Handler for ConversationRelay `dtmf` messages (caller keypresses). */
3566
- type DtmfHandler = (event: DtmfEvent) => Promise<void> | void;
4124
+
3567
4125
  /**
3568
- * Voice channel event callbacks extending base callbacks
4126
+ * Options accepted by {@link ConversationRelayProviderConfig}.
4127
+ *
4128
+ * `defaultTwimlOptions` is one of several TwiML layers that merge per-field;
4129
+ * see `ConversationRelayProvider.handleIncomingCall` (inbound) and
4130
+ * `ConversationRelayProvider.initiateOutboundConversation` (outbound) for the
4131
+ * full precedence order.
3569
4132
  */
3570
- interface VoiceChannelEvents extends BaseChannelEvents {
3571
- onSetup?: (data: {
3572
- callSid: string;
3573
- from: string;
3574
- to: string;
3575
- customParameters: Record<string, unknown> | undefined;
3576
- }) => void;
3577
- onPrompt?: (data: {
3578
- conversationId: ConversationId;
3579
- transcript: string;
3580
- userMemory?: TACMemoryResponse;
3581
- session?: ConversationSession;
3582
- abortSignal: AbortSignal;
3583
- }) => Promise<void> | void;
3584
- onInterrupt?: (data: {
3585
- conversationId: ConversationId;
3586
- utteranceUntilInterrupt: string | undefined;
3587
- durationUntilInterruptMs: number | undefined;
3588
- }) => void;
3589
- /** Caller keypress. See {@link VoiceChannel.onDtmf}. */
3590
- onDtmf?: DtmfHandler;
4133
+ interface ConversationRelayProviderConfigOptions extends BaseChannelOptions {
3591
4134
  /**
3592
- * Fired once the session and WebSocket registration exist — in orchestrated
3593
- * mode possibly before the first prompt, since the lookup starts at setup.
4135
+ * Static `VoiceTwiMLOptionsConversationRelay` applied to every call (inbound and outbound).
4136
+ * Controls the TwiML inside `<ConversationRelay>` — voice, language,
4137
+ * transcription provider, welcomeGreeting, `<Language>` children, etc. Use
4138
+ * this when the same ConversationRelay configuration is correct for every call.
4139
+ *
4140
+ * Per-call inbound customization is registered via
4141
+ * `VoiceChannel.onInboundCallTwiml(...)` (not on this config).
4142
+ *
4143
+ * Note: `customParameters` and `languages` replace wholesale when a
4144
+ * higher-priority layer sets them.
3594
4145
  */
3595
- onWebSocketConnected?: (data: {
3596
- conversationId: ConversationId;
3597
- }) => void;
3598
- onWebSocketDisconnected?: (data: {
3599
- conversationId: ConversationId;
3600
- }) => void;
4146
+ defaultTwimlOptions?: VoiceTwiMLOptionsConversationRelay;
4147
+ /**
4148
+ * Static {@link CallOptions} applied to every outbound call — the
4149
+ * `calls.create` parameters, including the call-event callback URLs. This is
4150
+ * the layer to use for a custom server or non-default routes: URLs set here
4151
+ * override the ones TAC would derive from `voicePublicDomain` +
4152
+ * `voiceCallEventPath`.
4153
+ */
4154
+ defaultCallOptions?: CallOptions;
4155
+ }
4156
+ /**
4157
+ * Configuration for {@link ConversationRelayProvider}, the default
4158
+ * {@link VoiceChannel} provider.
4159
+ *
4160
+ * TwiML configuration layers (highest precedence first):
4161
+ *
4162
+ * Inbound calls (`handleIncomingCall`):
4163
+ * 1. Output of the customizer registered via
4164
+ * `VoiceChannel.onInboundCallTwiml(...)` [optional]
4165
+ * 2. `defaultTwimlOptions` [optional]
4166
+ * 3. `handleIncomingCall(hostTwimlOptions)` [optional]
4167
+ * 4. TAC defaults
4168
+ *
4169
+ * Outbound calls (`initiateOutboundConversation`):
4170
+ * 1. `InitiateVoiceConversationOptions.twimlOptions` [optional]
4171
+ * 2. `defaultTwimlOptions` [optional]
4172
+ * 3. TAC defaults
4173
+ *
4174
+ * Calls-API parameters (`initiateOutboundConversation`):
4175
+ * 1. `InitiateVoiceConversationOptions.callOptions` [optional]
4176
+ * 2. `defaultCallOptions` [optional]
4177
+ * 3. Callback URLs derived from `TACConfig.voicePublicDomain` +
4178
+ * `voiceCallEventPath`, for handlers that are registered
4179
+ *
4180
+ * All layers merge per-field via key presence — only fields a layer explicitly
4181
+ * sets override lower layers. Arrays (`languages`) and nested objects
4182
+ * (`customParameters`) replace wholesale when set.
4183
+ *
4184
+ * Per-call inbound customization is registered via
4185
+ * `VoiceChannel.onInboundCallTwiml(...)` (not on this config).
4186
+ */
4187
+ declare class ConversationRelayProviderConfig extends VoiceProviderConfig {
4188
+ /**
4189
+ * Static `VoiceTwiMLOptionsConversationRelay` for the TwiML inside `<ConversationRelay>`, applied
4190
+ * to every call (inbound and outbound).
4191
+ */
4192
+ readonly defaultTwimlOptions?: VoiceTwiMLOptionsConversationRelay;
4193
+ /** Static {@link CallOptions} applied to every outbound call. */
4194
+ readonly defaultCallOptions?: CallOptions;
4195
+ constructor(options?: ConversationRelayProviderConfigOptions);
4196
+ createProvider(channel: VoiceChannel, tacConfig: TACConfig): VoiceProvider;
3601
4197
  }
3602
4198
  /**
3603
- * Voice Channel implementation for Twilio ConversationRelay
4199
+ * Pre-provider-split name for {@link ConversationRelayProviderConfigOptions} —
4200
+ * the shape `new VoiceChannel(tac, {...})` accepts. Kept so the shipped public
4201
+ * export stays valid across the provider refactor.
3604
4202
  *
3605
- * Handles voice conversations through WebSocket connections.
3606
- * Manages real-time audio streaming and conversation state.
4203
+ * @deprecated Use {@link ConversationRelayProviderConfigOptions} instead.
4204
+ */
4205
+ type VoiceChannelConfig = ConversationRelayProviderConfigOptions;
4206
+
4207
+ /**
4208
+ * A single in-flight streaming response, with the {@link AbortController} that
4209
+ * cancels it and whether any token has been written to the transport yet.
3607
4210
  */
3608
4211
  interface StreamTask {
3609
4212
  controller: AbortController;
3610
4213
  hasSentTokens: boolean;
3611
4214
  }
3612
- declare class VoiceChannel extends BaseChannel {
4215
+ /**
4216
+ * Twilio ConversationRelay: Twilio handles ASR/TTS and exchanges JSON
4217
+ * `setup`/`prompt`/`interrupt` messages over one WebSocket.
4218
+ *
4219
+ * This is the default provider {@link VoiceChannel} builds when none is passed
4220
+ * explicitly.
4221
+ */
4222
+ declare class ConversationRelayProvider extends VoiceProvider {
4223
+ /** @internal */
4224
+ get providerId(): string;
4225
+ /**
4226
+ * The owning channel's logger, so relocated ConversationRelay logic keeps
4227
+ * logging exactly as it did when it lived on `VoiceChannel`.
4228
+ */
4229
+ protected readonly logger: Logger;
4230
+ /** In-flight streaming responses, keyed by conversation. */
4231
+ protected readonly streamTasks: Map<ConversationId, StreamTask>;
4232
+ private readonly config;
4233
+ private readonly tacConfig;
4234
+ private readonly twimlBuilder;
3613
4235
  private readonly webSocketConnections;
3614
- private readonly voiceCallbacks;
3615
- private readonly streamTasks;
3616
4236
  private readonly promptQueues;
3617
4237
  private readonly initializationRetries;
3618
4238
  private readonly callSidToConversationId;
3619
4239
  private readonly MAX_INITIALIZATION_RETRIES;
3620
- private twilioClient;
3621
- private readonly voiceConfig;
3622
- private onInboundCallTwimlHandler;
3623
- private onCallStatusHandler;
3624
- private onAmdHandler;
3625
- private onRecordingHandler;
3626
- constructor(tac: TAC, options?: VoiceChannelConfig);
3627
- /**
3628
- * Register a callback that produces per-call overrides for the TwiML inside
3629
- * `<ConversationRelay>` on inbound calls.
3630
- *
3631
- * The callback receives a framework-neutral {@link TwiMLRequest} (parsed from
3632
- * the Twilio webhook form) and returns {@link TwiMLOptions}. Fields the
3633
- * callback explicitly sets override `defaultTwimlOptions` and TAC defaults;
3634
- * unset fields fall through.
3635
- *
3636
- * @example
3637
- * ```typescript
3638
- * voiceChannel.onInboundCallTwiml(async req => {
3639
- * if (req.callerCountry === 'MX') {
3640
- * return { language: 'es-MX', welcomeGreeting: '¡Hola!' };
3641
- * }
3642
- * return {};
3643
- * });
3644
- * ```
3645
- *
3646
- * Outbound calls don't use this — pass per-call TwiML via
3647
- * `InitiateVoiceConversationOptions.twimlOptions` directly.
3648
- */
3649
- onInboundCallTwiml(callback: InboundCallTwimlHandler): void;
3650
- /**
3651
- * Register a handler for Twilio `statusCallback` webhooks.
3652
- *
3653
- * This is the Calls-API status callback (call disposition), not the
3654
- * ConversationRelay session callback — see
3655
- * {@link handleConversationRelayCallback}.
3656
- *
3657
- * Registering does two things: it stores the handler, and it makes later
3658
- * outbound calls pass `statusCallback` to `calls.create`. With no handler
3659
- * registered TAC omits that parameter, so Twilio has nowhere to post and the
3660
- * event never arrives.
3661
- *
3662
- * Twilio reports only the terminal event by default, which covers every
3663
- * disposition; set `CallOptions.statusCallbackEvent` for ringing/answered.
3664
- *
3665
- * @example
3666
- * ```typescript
3667
- * voiceChannel.onCallStatus(async event => {
3668
- * if (event.isUnreached) {
3669
- * // queue a retry
3670
- * }
3671
- * });
3672
- * ```
3673
- */
3674
- onCallStatus(callback: CallStatusHandler): void;
3675
- /**
3676
- * Register a handler for Twilio `asyncAmdStatusCallback` webhooks.
3677
- *
3678
- * Registering makes later outbound calls pass `asyncAmdStatusCallback` to
3679
- * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
3680
- * post the result. It does not enable detection — that's per-call, via
3681
- * `CallOptions.machineDetection` and `asyncAmd`, both of which are required
3682
- * for this to fire (at most once per call).
3683
- *
3684
- * @example
3685
- * ```typescript
3686
- * voiceChannel.onAmd(async event => {
3687
- * if (event.isMachine) {
3688
- * await voiceChannel.endCall(event.callSid); // voicemail → hang up
3689
- * }
3690
- * });
3691
- * ```
3692
- */
3693
- onAmd(callback: AmdHandler): void;
3694
- /**
3695
- * Register a handler for Twilio `recordingStatusCallback` webhooks.
3696
- *
3697
- * Registering makes later outbound calls pass `recordingStatusCallback` to
3698
- * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
3699
- * post. It does not start recording — that's `CallOptions.record`, which is
3700
- * required for this to fire.
3701
- *
3702
- * @example
3703
- * ```typescript
3704
- * voiceChannel.onRecording(async event => {
3705
- * if (event.recordingStatus === 'completed') {
3706
- * // store event.recordingUrl
3707
- * }
3708
- * });
3709
- * ```
3710
- */
3711
- onRecording(callback: RecordingHandler): void;
3712
- /**
3713
- * Register a handler for DTMF keypresses, called once per key in order.
3714
- *
3715
- * Requires `dtmfDetection: true` on the ConversationRelay config — without it
3716
- * Twilio sends nothing and this never fires. Digits aren't buffered, so
3717
- * accumulating a multi-digit entry is the handler's job.
3718
- *
3719
- * A keypress initializes the conversation just as a prompt does, since a
3720
- * caller can type without ever speaking; if that fails the digit still
3721
- * arrives, with `conversationId` and `session` undefined. Keypresses don't
3722
- * cancel in-flight streaming on their own — that's a separate `interrupt`
3723
- * message, sent when `interruptible` includes `dtmf`.
3724
- *
3725
- * @example
3726
- * ```typescript
3727
- * const digits = new Map<string, string>();
3728
- *
3729
- * voiceChannel.onDtmf(({ conversationId, digit }) => {
3730
- * if (!conversationId) return;
3731
- * digits.set(conversationId, (digits.get(conversationId) ?? '') + digit);
3732
- * });
3733
- * ```
3734
- */
3735
- onDtmf(callback: DtmfHandler): void;
3736
- /**
3737
- * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
3738
- * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
3739
- */
3740
- private resolveWebsocketUrl;
3741
- /**
3742
- * Resolve the default `<Connect action=...>` cleanup URL.
3743
- *
3744
- * Returns undefined if `voicePublicDomain` isn't set; that's fine because
3745
- * actionUrl has higher-priority layers (customizer, twimlOptions, Studio
3746
- * handoff) above this fallback.
3747
- */
3748
- private resolveDefaultActionUrl;
3749
- private getTwilioClient;
3750
- get channelType(): ChannelType;
3751
- /**
3752
- * Register event callbacks (override for Voice-specific events)
3753
- */
3754
- on(event: string, callback: (...args: any[]) => void): void;
3755
- /**
3756
- * Process conversation webhooks for cleanup.
3757
- *
3758
- * Voice channel processes CONVERSATION_UPDATED events:
3759
- * - CLOSED status: Clean up local session state
3760
- *
3761
- * Note: Conversation tracking uses instance-local memory. In multi-instance
3762
- * deployments, webhooks may route to a different instance, preventing cleanup.
3763
- *
3764
- * @param payload - Raw webhook event data from Twilio
3765
- * @param idempotencyToken - Optional Twilio idempotency token from request headers
3766
- */
3767
- processWebhook(payload: unknown, idempotencyToken?: string): Promise<void>;
3768
- /**
3769
- * Handle conversation updated event
3770
- */
3771
- private handleConversationUpdated;
4240
+ constructor(channel: VoiceChannel, tacConfig: TACConfig, config: ConversationRelayProviderConfig);
4241
+ get channelName(): string;
3772
4242
  /**
3773
4243
  * Get active WebSocket connection for a conversation
3774
4244
  */
3775
- getWebsocket(conversationId: ConversationId): WebSocket | null;
4245
+ getWebSocket(conversationId: ConversationId): WebSocket | null;
3776
4246
  /**
3777
4247
  * Poll Conversation Orchestrator for the conversation ConversationRelay
3778
4248
  * created for `callSid`, then register the local session and WebSocket.
@@ -3783,7 +4253,7 @@ declare class VoiceChannel extends BaseChannel {
3783
4253
  /**
3784
4254
  * Handle WebSocket connection from ConversationRelay
3785
4255
  */
3786
- handleWebSocketConnection(ws: WebSocket): void;
4256
+ handleWebSocket(ws: WebSocket): void;
3787
4257
  /**
3788
4258
  * Handle WebSocket prompt message (user speech)
3789
4259
  */
@@ -3806,6 +4276,12 @@ declare class VoiceChannel extends BaseChannel {
3806
4276
  * Send voice response via WebSocket
3807
4277
  */
3808
4278
  sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
4279
+ /**
4280
+ * Send the ConversationRelay `end` message if the session has a handoff
4281
+ * pending, so the caller is transferred once the response has been delivered.
4282
+ * No-op when nothing is pending.
4283
+ */
4284
+ private flushPendingHandoff;
3809
4285
  /**
3810
4286
  * Send a streaming voice response via WebSocket, token by token.
3811
4287
  *
@@ -3815,26 +4291,58 @@ declare class VoiceChannel extends BaseChannel {
3815
4291
  * interrupted), iteration stops and no final marker is sent (the interrupt
3816
4292
  * handler sends the finalization instead).
3817
4293
  *
4294
+ * Once the stream completes, a handoff pending on the session is delivered as
4295
+ * the WS `end` message, matching {@link sendResponse}. An aborted stream
4296
+ * leaves it pending for the next response.
4297
+ *
3818
4298
  * @returns The accumulated full response text.
3819
4299
  */
3820
4300
  sendStreamingResponse(conversationId: ConversationId, stream: AsyncIterable<string>, options?: {
3821
4301
  signal?: AbortSignal;
3822
4302
  }): Promise<string>;
3823
4303
  /**
3824
- * Generate the TwiML response for an incoming voice call.
4304
+ * Start tracking a streaming task for a conversation
3825
4305
  *
3826
- * ConversationRelay automatically handles conversation creation and
3827
- * participant management via the `conversationConfiguration` parameter.
4306
+ * @param conversationId - The conversation ID
4307
+ * @returns The stream task with its AbortController
4308
+ */
4309
+ startStreamTask(conversationId: ConversationId): StreamTask;
4310
+ /**
4311
+ * Cancel an active streaming task
3828
4312
  *
3829
- * The WebSocket URL and default session-cleanup action URL are derived from
3830
- * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` /
3831
- * `voiceActionPath`.
4313
+ * @param conversationId - The conversation ID
4314
+ * @returns true if a task was cancelled, false otherwise
4315
+ */
4316
+ cancelStreamTask(conversationId: ConversationId): boolean;
4317
+ /**
4318
+ * Complete a streaming task (remove from tracking)
4319
+ *
4320
+ * @param conversationId - The conversation ID
4321
+ */
4322
+ completeStreamTask(conversationId: ConversationId): void;
4323
+ /**
4324
+ * Check if a stream task is active
4325
+ *
4326
+ * @param conversationId - The conversation ID
4327
+ * @returns true if an active task exists
4328
+ */
4329
+ hasActiveStreamTask(conversationId: ConversationId): boolean;
4330
+ /**
4331
+ * Generate the TwiML response for an incoming voice call.
4332
+ *
4333
+ * ConversationRelay automatically handles conversation creation and
4334
+ * participant management via the `conversationConfiguration` parameter.
4335
+ *
4336
+ * The WebSocket URL and default session-cleanup action URL are derived from
4337
+ * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` /
4338
+ * `voiceActionPath`.
3832
4339
  *
3833
4340
  * TwiML fields are merged per-field, highest precedence first:
3834
4341
  * 1. Output of the customizer registered via
3835
4342
  * `VoiceChannel.onInboundCallTwiml(...)` if configured and `twimlRequest`
3836
4343
  * is given. (Application-owned.)
3837
- * 2. `VoiceChannelConfig.defaultTwimlOptions` — per-channel defaults.
4344
+ * 2. `ConversationRelayProviderConfig.defaultTwimlOptions` — per-channel
4345
+ * defaults.
3838
4346
  * 3. `hostTwimlOptions` — per-call transport facts supplied by the host (the
3839
4347
  * code owning the route), e.g. a per-call `websocketUrl` with an affinity
3840
4348
  * token.
@@ -3857,309 +4365,1926 @@ declare class VoiceChannel extends BaseChannel {
3857
4365
  * `websocketUrl`), layered below `defaultTwimlOptions` and the application
3858
4366
  * customizer but above the TAC defaults.
3859
4367
  * @returns TwiML XML string for call connection.
4368
+ * @throws {Error} if either options layer isn't a
4369
+ * {@link VoiceTwiMLOptionsConversationRelay}.
4370
+ */
4371
+ handleIncomingCall(twimlRequest?: TwiMLRequest, options?: {
4372
+ hostTwimlOptions?: VoiceTwiMLOptions;
4373
+ }): Promise<string>;
4374
+ /**
4375
+ * Narrow provider-agnostic {@link VoiceTwiMLOptions} to this provider's
4376
+ * concrete shape. `VoiceProvider.handleIncomingCall` is typed against the
4377
+ * base so every provider can accept its own TwiML options, so the
4378
+ * ConversationRelay shape has to be established at runtime.
4379
+ *
4380
+ * @param value - Options from a caller or the application customizer.
4381
+ * @param label - What produced `value`, for the error message.
4382
+ */
4383
+ private narrowTwimlOptions;
4384
+ /**
4385
+ * Overlay `perCall` onto `ConversationRelayProviderConfig.defaultCallOptions`.
4386
+ *
4387
+ * Per-field via key presence, the same convention `TwiMLBuilderBase.overlayFields`
4388
+ * uses for TwiML options — so a per-call `{ machineDetection: undefined }`
4389
+ * explicitly clears the channel default rather than falling through to it.
4390
+ *
4391
+ * The result is always validated, for two reasons: a combination only
4392
+ * reachable by layering — per-call clearing `machineDetection` while the
4393
+ * default set `asyncAmd` — must still fail instead of reaching Twilio, and
4394
+ * `ConversationRelayProviderConfigOptions` is a plain interface, so
4395
+ * `defaultCallOptions` has had no runtime validation of its own.
4396
+ */
4397
+ private mergeCallOptions;
4398
+ /**
4399
+ * Build the extra arguments for `client.calls.create`.
4400
+ *
4401
+ * Layers, highest precedence first: this call's `callOptions`,
4402
+ * `ConversationRelayProviderConfig.defaultCallOptions`, then callback URLs
4403
+ * derived from `voicePublicDomain` + `voiceCallEventPath`.
4404
+ *
4405
+ * A URL is derived only when its handler is registered. That's a deliberate
4406
+ * deviation from `websocketUrl` / `actionUrl`, which derive unconditionally:
4407
+ * those are load-bearing, so a wrong one fails loudly on the first call,
4408
+ * whereas an unwanted call-event URL fails as silent 11200 alerts for a
4409
+ * feature nobody asked for. Set the URLs in `defaultCallOptions` when TAC
4410
+ * isn't serving the routes.
4411
+ */
4412
+ private buildCallParams;
4413
+ /**
4414
+ * Initiate an outbound voice conversation
4415
+ *
4416
+ * Places an outbound call with inline TwiML that connects to ConversationRelay.
4417
+ * The conversationConfiguration attribute tells CO to create and manage the
4418
+ * conversation during passive hydration. The session is initialized when the
4419
+ * background callSid lookup started at WebSocket setup finds it.
4420
+ *
4421
+ * TwiML fields are merged per-field, highest precedence first:
4422
+ * 1. `options.twimlOptions` — per-call overrides
4423
+ * 2. `ConversationRelayProviderConfig.defaultTwimlOptions` — channel-wide
4424
+ * defaults
4425
+ * 3. TAC defaults: welcome greeting, `conversationConfiguration` from
4426
+ * `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
4427
+ * derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
4428
+ *
4429
+ * Calls-API parameters merge the same way:
4430
+ * 1. `options.callOptions` — per-call overrides
4431
+ * 2. `ConversationRelayProviderConfig.defaultCallOptions` — channel-wide
4432
+ * defaults
4433
+ * 3. Callback URLs derived from `TACConfig.voicePublicDomain` +
4434
+ * `voiceCallEventPath`, for handlers that are registered
4435
+ *
4436
+ * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
4437
+ * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
4438
+ * `options.websocketUrl`.
4439
+ */
4440
+ initiateOutboundConversation(options: InitiateVoiceConversationOptions): Promise<InitiateVoiceConversationResult>;
4441
+ /**
4442
+ * Handle ConversationRelay callback from Twilio. Cleans up on call completion
4443
+ * in voice-only mode; in orchestrated mode the CO webhook owns cleanup.
4444
+ *
4445
+ * @param rawPayload - Callback payload from Twilio
4446
+ * @returns Response with status, content, and content type
4447
+ */
4448
+ handleTwilioProviderCallback(rawPayload: Record<string, unknown>): Promise<TwilioProviderCallbackResponse>;
4449
+ /**
4450
+ * Generate TwiML to connect a call to ConversationRelay.
4451
+ * Validates configuration with Zod before generating TwiML.
4452
+ *
4453
+ * @param config - ConversationRelay configuration (url, transcription, TTS, etc.)
4454
+ * @param options - Optional settings for parameters and the Connect verb
4455
+ * @returns TwiML XML string
4456
+ * @throws {Error} if config validation fails
4457
+ */
4458
+ connectConversationRelay(config: ConversationRelayConfig, options?: {
4459
+ parameters?: CustomParameters;
4460
+ actionUrl?: string;
4461
+ }): string;
4462
+ /**
4463
+ * Drop this provider's ConversationRelay transport state on channel shutdown.
4464
+ *
4465
+ * Note: WebSocket connections are managed by the server and closed there.
4466
+ * This method only cleans up internal provider state.
4467
+ */
4468
+ shutdown(): void;
4469
+ }
4470
+
4471
+ /**
4472
+ * Callback that produces per-call overrides for the TwiML inside
4473
+ * `<ConversationRelay>` on inbound calls. Receives a framework-neutral
4474
+ * {@link TwiMLRequest} and returns {@link VoiceTwiMLOptionsConversationRelay}.
4475
+ *
4476
+ * Stays typed against the ConversationRelay subtype rather than the
4477
+ * provider-agnostic base ({@link VoiceProvider.handleIncomingCall} is widened
4478
+ * to the base, this consumer-facing surface is not): the base has only
4479
+ * optional shared fields, so TypeScript's object-literal freshness check
4480
+ * rejects the documented inline form `async () => ({ voice: '...' })` for
4481
+ * having no properties in common with it. It widens once a second
4482
+ * inbound-capable provider exists.
4483
+ */
4484
+ type InboundCallTwimlHandler = (req: TwiMLRequest) => Promise<VoiceTwiMLOptionsConversationRelay>;
4485
+ /** Handler for Twilio `statusCallback` webhooks. */
4486
+ type CallStatusHandler = (event: CallStatusEvent) => Promise<void> | void;
4487
+ /** Handler for Twilio `asyncAmdStatusCallback` webhooks. */
4488
+ type AmdHandler = (event: AmdEvent) => Promise<void> | void;
4489
+ /** Handler for Twilio `recordingStatusCallback` webhooks. */
4490
+ type RecordingHandler = (event: RecordingEvent) => Promise<void> | void;
4491
+ /** One ConversationRelay keypress, as delivered to a {@link DtmfHandler}. */
4492
+ interface DtmfEvent {
4493
+ /**
4494
+ * Undefined only when the keypress beat conversation setup: `dtmf` before
4495
+ * ConversationRelay's `setup`, or an orchestrated-mode lookup that failed.
4496
+ */
4497
+ conversationId: ConversationId | undefined;
4498
+ /** Undefined only before ConversationRelay's `setup` message. */
4499
+ callSid: string | undefined;
4500
+ /** The key pressed: `0`-`9`, `*`, `#`, or `A`-`D`. */
4501
+ digit: string;
4502
+ /** Present whenever `conversationId` is. */
4503
+ session?: ConversationSession;
4504
+ }
4505
+ /** Handler for ConversationRelay `dtmf` messages (caller keypresses). */
4506
+ type DtmfHandler = (event: DtmfEvent) => Promise<void> | void;
4507
+ /**
4508
+ * Voice channel event callbacks extending base callbacks
4509
+ */
4510
+ interface VoiceChannelEvents extends BaseChannelEvents {
4511
+ onSetup?: (data: {
4512
+ callSid: string;
4513
+ from: string;
4514
+ to: string;
4515
+ customParameters: Record<string, unknown> | undefined;
4516
+ }) => void;
4517
+ onPrompt?: (data: {
4518
+ conversationId: ConversationId;
4519
+ transcript: string;
4520
+ userMemory?: TACMemoryResponse;
4521
+ session?: ConversationSession;
4522
+ abortSignal: AbortSignal;
4523
+ }) => Promise<void> | void;
4524
+ onInterrupt?: (data: {
4525
+ conversationId: ConversationId;
4526
+ utteranceUntilInterrupt: string | undefined;
4527
+ durationUntilInterruptMs: number | undefined;
4528
+ }) => void;
4529
+ /** Caller keypress. See {@link VoiceChannel.onDtmf}. */
4530
+ onDtmf?: DtmfHandler;
4531
+ /**
4532
+ * Fired once the session and WebSocket registration exist — in orchestrated
4533
+ * mode possibly before the first prompt, since the lookup starts at setup.
4534
+ */
4535
+ onWebSocketConnected?: (data: {
4536
+ conversationId: ConversationId;
4537
+ }) => void;
4538
+ onWebSocketDisconnected?: (data: {
4539
+ conversationId: ConversationId;
4540
+ }) => void;
4541
+ }
4542
+ /**
4543
+ * Voice Channel for handling voice-based conversations over a WebSocket.
4544
+ *
4545
+ * The real-time media transport lives on a {@link VoiceProvider} — by default
4546
+ * {@link ConversationRelayProvider}. `VoiceChannel` keeps the Calls-API
4547
+ * lifecycle (call events, hangup), conversation bookkeeping and webhook
4548
+ * processing, and delegates everything transport-shaped to the provider.
4549
+ */
4550
+ declare class VoiceChannel extends BaseChannel {
4551
+ private readonly provider;
4552
+ private readonly voiceCallbacks;
4553
+ private twilioClient;
4554
+ private onInboundCallTwimlHandler;
4555
+ private onCallStatusHandler;
4556
+ private onAmdHandler;
4557
+ private onRecordingHandler;
4558
+ /**
4559
+ * @param tac - The owning {@link TAC} instance.
4560
+ * @param options - Either a {@link VoiceProviderConfig} selecting the media
4561
+ * provider, or a plain object — shorthand for
4562
+ * {@link ConversationRelayProviderConfig}, which is what TAC builds when no
4563
+ * provider config is given.
4564
+ */
4565
+ constructor(tac: TAC, options?: VoiceProviderConfig | ConversationRelayProviderConfigOptions);
4566
+ /**
4567
+ * The {@link BaseChannelOptions} to hand `BaseChannel`. A provider config
4568
+ * replays the options it retained (with its resolved `memoryMode`, which is
4569
+ * writable after construction); a plain options object is passed through. Both
4570
+ * paths therefore honour `dedupCapacity` and friends identically.
4571
+ */
4572
+ private static toBaseOptions;
4573
+ /**
4574
+ * Resolve the provider config: an explicit {@link VoiceProviderConfig} as-is,
4575
+ * anything else wrapped as a {@link ConversationRelayProviderConfig}.
4576
+ */
4577
+ private static toProviderConfig;
4578
+ /**
4579
+ * Register a callback that produces per-call overrides for the TwiML inside
4580
+ * `<ConversationRelay>` on inbound calls.
4581
+ *
4582
+ * The callback receives a framework-neutral {@link TwiMLRequest} (parsed from
4583
+ * the Twilio webhook form) and returns
4584
+ * {@link VoiceTwiMLOptionsConversationRelay}. Fields the
4585
+ * callback explicitly sets override `defaultTwimlOptions` and TAC defaults;
4586
+ * unset fields fall through.
4587
+ *
4588
+ * @example
4589
+ * ```typescript
4590
+ * voiceChannel.onInboundCallTwiml(async req => {
4591
+ * if (req.callerCountry === 'MX') {
4592
+ * return { language: 'es-MX', welcomeGreeting: '¡Hola!' };
4593
+ * }
4594
+ * return {};
4595
+ * });
4596
+ * ```
4597
+ *
4598
+ * Outbound calls don't use this — pass per-call TwiML via
4599
+ * `InitiateVoiceConversationOptions.twimlOptions` directly.
4600
+ */
4601
+ onInboundCallTwiml(callback: InboundCallTwimlHandler): void;
4602
+ /**
4603
+ * Register a handler for Twilio `statusCallback` webhooks.
4604
+ *
4605
+ * This is the Calls-API status callback (call disposition), not the
4606
+ * ConversationRelay session callback — see
4607
+ * {@link handleTwilioProviderCallback}.
4608
+ *
4609
+ * Registering does two things: it stores the handler, and it makes later
4610
+ * outbound calls pass `statusCallback` to `calls.create`. With no handler
4611
+ * registered TAC omits that parameter, so Twilio has nowhere to post and the
4612
+ * event never arrives.
4613
+ *
4614
+ * Twilio reports only the terminal event by default, which covers every
4615
+ * disposition; set `CallOptions.statusCallbackEvent` for ringing/answered.
4616
+ *
4617
+ * @example
4618
+ * ```typescript
4619
+ * voiceChannel.onCallStatus(async event => {
4620
+ * if (event.isUnreached) {
4621
+ * // queue a retry
4622
+ * }
4623
+ * });
4624
+ * ```
4625
+ */
4626
+ onCallStatus(callback: CallStatusHandler): void;
4627
+ /**
4628
+ * Register a handler for Twilio `asyncAmdStatusCallback` webhooks.
4629
+ *
4630
+ * Registering makes later outbound calls pass `asyncAmdStatusCallback` to
4631
+ * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
4632
+ * post the result. It does not enable detection — that's per-call, via
4633
+ * `CallOptions.machineDetection` and `asyncAmd`, both of which are required
4634
+ * for this to fire (at most once per call).
4635
+ *
4636
+ * @example
4637
+ * ```typescript
4638
+ * voiceChannel.onAmd(async event => {
4639
+ * if (event.isMachine) {
4640
+ * await voiceChannel.endCall(event.callSid); // voicemail → hang up
4641
+ * }
4642
+ * });
4643
+ * ```
4644
+ */
4645
+ onAmd(callback: AmdHandler): void;
4646
+ /**
4647
+ * Register a handler for Twilio `recordingStatusCallback` webhooks.
4648
+ *
4649
+ * Registering makes later outbound calls pass `recordingStatusCallback` to
4650
+ * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
4651
+ * post. It does not start recording — that's `CallOptions.record`, which is
4652
+ * required for this to fire.
4653
+ *
4654
+ * @example
4655
+ * ```typescript
4656
+ * voiceChannel.onRecording(async event => {
4657
+ * if (event.recordingStatus === 'completed') {
4658
+ * // store event.recordingUrl
4659
+ * }
4660
+ * });
4661
+ * ```
4662
+ */
4663
+ onRecording(callback: RecordingHandler): void;
4664
+ /**
4665
+ * Register a handler for DTMF keypresses, called once per key in order.
4666
+ *
4667
+ * Requires `dtmfDetection: true` on the ConversationRelay config — without it
4668
+ * Twilio sends nothing and this never fires. Digits aren't buffered, so
4669
+ * accumulating a multi-digit entry is the handler's job.
4670
+ *
4671
+ * A keypress initializes the conversation just as a prompt does, since a
4672
+ * caller can type without ever speaking; if that fails the digit still
4673
+ * arrives, with `conversationId` and `session` undefined. Keypresses don't
4674
+ * cancel in-flight streaming on their own — that's a separate `interrupt`
4675
+ * message, sent when `interruptible` includes `dtmf`.
4676
+ *
4677
+ * @example
4678
+ * ```typescript
4679
+ * const digits = new Map<string, string>();
4680
+ *
4681
+ * voiceChannel.onDtmf(({ conversationId, digit }) => {
4682
+ * if (!conversationId) return;
4683
+ * digits.set(conversationId, (digits.get(conversationId) ?? '') + digit);
4684
+ * });
4685
+ * ```
4686
+ */
4687
+ onDtmf(callback: DtmfHandler): void;
4688
+ /**
4689
+ * The registered call-event handlers, for a `VoiceProvider` deciding which
4690
+ * callback URLs to derive. A provider is not a subclass of `VoiceChannel`,
4691
+ * so the `private` fields are genuinely out of reach without this.
4692
+ *
4693
+ * @internal
4694
+ */
4695
+ getCallEventHandlers(): {
4696
+ status: CallStatusHandler | undefined;
4697
+ amd: AmdHandler | undefined;
4698
+ recording: RecordingHandler | undefined;
4699
+ };
4700
+ /**
4701
+ * This channel's `TACConfig`, for a `VoiceProvider` deriving default URLs.
4702
+ * `BaseChannel.config` is `protected`, and a provider is not a subclass.
4703
+ *
4704
+ * @internal
4705
+ */
4706
+ getTacConfig(): TACConfig;
4707
+ /**
4708
+ * This channel's logger, so a provider's relocated logic keeps logging under
4709
+ * the same name it did when it lived on `VoiceChannel`.
4710
+ *
4711
+ * @internal
4712
+ */
4713
+ getLoggerInternal(): Logger;
4714
+ /**
4715
+ * The Conversation Orchestrator client, or `null` in ConversationRelay-only
4716
+ * mode.
4717
+ *
4718
+ * @internal
4719
+ */
4720
+ getConversationClientInternal(): ConversationClient | null;
4721
+ /**
4722
+ * The lazily built Twilio REST client, for a provider placing outbound calls.
4723
+ *
4724
+ * @internal
4725
+ */
4726
+ getTwilioClientInternal(): ReturnType<typeof Twilio>;
4727
+ /**
4728
+ * Whether Conversation Orchestrator is configured. Providers branch on this
4729
+ * to decide who owns conversation cleanup.
4730
+ *
4731
+ * @internal
4732
+ */
4733
+ isOrchestratorEnabledInternal(): boolean;
4734
+ /**
4735
+ * Voice event callbacks registered via {@link on}, for a provider to fire.
4736
+ *
4737
+ * @internal
4738
+ */
4739
+ getVoiceCallbacks(): VoiceChannelEvents;
4740
+ /**
4741
+ * The inbound-TwiML customizer registered via {@link onInboundCallTwiml}, for
4742
+ * a provider building the inbound response.
4743
+ *
4744
+ * @internal
4745
+ */
4746
+ getInboundCallTwimlHandler(): InboundCallTwimlHandler | undefined;
4747
+ /**
4748
+ * Start tracking a conversation session. Forwards to
4749
+ * `BaseChannel.startConversation`.
4750
+ *
4751
+ * @internal
4752
+ */
4753
+ startConversationInternal(conversationId: ConversationId, profileId?: ProfileId): ConversationSession;
4754
+ /**
4755
+ * End a tracked conversation session. Forwards to
4756
+ * `BaseChannel.endConversation`.
4757
+ *
4758
+ * @internal
4759
+ */
4760
+ endConversationInternal(conversationId: ConversationId): Promise<void>;
4761
+ /**
4762
+ * Retrieve memory when `memoryMode` calls for it. Forwards to
4763
+ * `BaseChannel.retrieveMemoryIfEnabled`.
4764
+ *
4765
+ * @internal
4766
+ */
4767
+ retrieveMemoryInternal(session: ConversationSession, query?: string): Promise<TACMemoryResponse | undefined>;
4768
+ /**
4769
+ * Report an error through the channel's `onError` callback and logger.
4770
+ * Forwards to `BaseChannel.handleError`.
4771
+ *
4772
+ * @internal
4773
+ */
4774
+ handleErrorInternal(error: Error, context?: Record<string, unknown>): void;
4775
+ private getTwilioClient;
4776
+ get channelType(): ChannelType;
4777
+ /**
4778
+ * Register event callbacks (override for Voice-specific events)
4779
+ */
4780
+ on(event: string, callback: (...args: any[]) => void): void;
4781
+ /**
4782
+ * Process conversation webhooks for cleanup.
4783
+ *
4784
+ * Voice channel processes CONVERSATION_UPDATED events:
4785
+ * - CLOSED status: Clean up local session state
4786
+ *
4787
+ * Note: Conversation tracking uses instance-local memory. In multi-instance
4788
+ * deployments, webhooks may route to a different instance, preventing cleanup.
4789
+ *
4790
+ * @param payload - Raw webhook event data from Twilio
4791
+ * @param idempotencyToken - Optional Twilio idempotency token from request headers
4792
+ */
4793
+ processWebhook(payload: unknown, idempotencyToken?: string): Promise<void>;
4794
+ /**
4795
+ * Handle conversation updated event
4796
+ */
4797
+ private handleConversationUpdated;
4798
+ /**
4799
+ * Get active WebSocket connection for a conversation
4800
+ */
4801
+ getWebsocket(conversationId: ConversationId): WebSocket | null;
4802
+ /**
4803
+ * Hand one WebSocket connection to the active provider, which drives its
4804
+ * lifecycle from accept to disconnect.
4805
+ *
4806
+ * @param ws - The accepted WebSocket, from ConversationRelay or whatever
4807
+ * transport the active provider serves.
4808
+ */
4809
+ handleWebSocketConnection(ws: WebSocket): void;
4810
+ /**
4811
+ * Send voice response via WebSocket
4812
+ */
4813
+ sendResponse(conversationId: ConversationId, message: string, metadata?: Record<string, unknown>): Promise<void>;
4814
+ /**
4815
+ * Send a streaming voice response through the active provider's transport,
4816
+ * token by token. Delegates to the active provider — see
4817
+ * {@link ConversationRelayProvider.sendStreamingResponse} for the token
4818
+ * protocol and abort semantics.
4819
+ *
4820
+ * @param conversationId - Conversation whose transport receives the tokens.
4821
+ * @param stream - Async iterable of text chunks to relay as they arrive.
4822
+ * @param options - Additional per-call inputs.
4823
+ * @param options.signal - Aborts the stream mid-flight, e.g. when the caller
4824
+ * interrupts.
4825
+ * @returns The accumulated full response text.
4826
+ */
4827
+ sendStreamingResponse(conversationId: ConversationId, stream: AsyncIterable<string>, options?: {
4828
+ signal?: AbortSignal;
4829
+ }): Promise<string>;
4830
+ /**
4831
+ * Generate the response for an incoming voice call. Delegates to the active
4832
+ * provider — see {@link ConversationRelayProvider.handleIncomingCall} for the
4833
+ * full TwiML merge/precedence rules (only meaningful for that provider; a
4834
+ * provider with no inbound story declines instead).
4835
+ *
4836
+ * @param twimlRequest - Parsed Twilio webhook fields. Passed to the customizer
4837
+ * registered via {@link onInboundCallTwiml}, if one is configured.
4838
+ * @param options - Additional per-call inputs.
4839
+ * @param options.hostTwimlOptions - Per-call TwiML supplied by a custom
4840
+ * in-process host (e.g. an affinity-routed deployment injecting a per-call
4841
+ * `websocketUrl`). Typed against the ConversationRelay subtype for the same
4842
+ * reason as {@link InboundCallTwimlHandler}.
4843
+ * @returns TwiML XML string for call connection.
4844
+ */
4845
+ handleIncomingCall(twimlRequest?: TwiMLRequest, options?: {
4846
+ hostTwimlOptions?: VoiceTwiMLOptionsConversationRelay;
4847
+ }): Promise<string>;
4848
+ /**
4849
+ * Initiate an outbound voice conversation. Delegates to the active provider —
4850
+ * see {@link ConversationRelayProvider.initiateOutboundConversation} for the
4851
+ * TwiML and Calls-API merge/precedence rules.
4852
+ *
4853
+ * {@link ConversationRelayProvider} and `OpenAIRealtimeProvider` place
4854
+ * outbound calls; any other provider declines.
4855
+ *
4856
+ * @param options - Destination, per-call TwiML and Calls-API overrides.
4857
+ * `OpenAIRealtimeProvider` additionally accepts a per-call `sessionConfig`.
4858
+ * Each provider validates against its own schema and rejects the other's.
4859
+ * @returns The placed call's `callSid`.
4860
+ */
4861
+ initiateOutboundConversation(options: InitiateVoiceConversationOptions): Promise<InitiateVoiceConversationResult>;
4862
+ /**
4863
+ * Handle the provider's own out-of-band lifecycle webhook from Twilio.
4864
+ *
4865
+ * Not every provider has one; those that don't inherit a plain 200
4866
+ * acknowledgement. ConversationRelay posts here when a session ends, and
4867
+ * cleans up on call completion in voice-only mode — in orchestrated mode the
4868
+ * CO webhook owns cleanup.
4869
+ *
4870
+ * @param payload - Raw callback payload from Twilio; the provider validates it.
4871
+ * @returns Response with status, content, and content type
4872
+ */
4873
+ handleTwilioProviderCallback(payload: Record<string, unknown>): Promise<TwilioProviderCallbackResponse>;
4874
+ /**
4875
+ * @deprecated Use {@link VoiceChannel.handleTwilioProviderCallback} instead.
4876
+ */
4877
+ handleConversationRelayCallback(payload: ConversationRelayCallbackPayload): Promise<TwilioProviderCallbackResponse>;
4878
+ /**
4879
+ * Whether a call-webhook payload belongs to the configured account.
4880
+ *
4881
+ * Twilio signature validation already gates the route; this is defense in
4882
+ * depth. A payload with no `AccountSid` is allowed through.
4883
+ *
4884
+ * Subaccounts: events carry the SID the call was placed on, so configure TAC
4885
+ * with that account or its events get dropped here.
4886
+ */
4887
+ private callEventAccountOk;
4888
+ /**
4889
+ * Parse a call-event webhook form and dispatch it to its handler.
4890
+ *
4891
+ * Returns 400 when the payload can't be parsed (no `CallSid`) or the handler
4892
+ * throws — better than handing Twilio a 200 for an event that wasn't
4893
+ * processed. Everything else, including no handler registered and an
4894
+ * account mismatch, is a 200 no-op.
4895
+ */
4896
+ private dispatchCallEvent;
4897
+ /**
4898
+ * Handle a Twilio `statusCallback` webhook.
4899
+ *
4900
+ * The developer routes the request here (`TACServer` does this automatically
4901
+ * for its `/status` call-event route). Parsed into a {@link CallStatusEvent}
4902
+ * and dispatched to the {@link onCallStatus} handler. No-op if no handler is
4903
+ * registered.
4904
+ *
4905
+ * @param form - Raw form data from the webhook request.
4906
+ */
4907
+ handleCallStatusEvent(form: Record<string, string>): Promise<{
4908
+ status: number;
4909
+ content: string;
4910
+ contentType: string;
4911
+ }>;
4912
+ /**
4913
+ * Handle a Twilio `asyncAmdStatusCallback` webhook.
4914
+ *
4915
+ * The developer routes the request here (`TACServer` does this automatically
4916
+ * for its `/amd` call-event route). Parsed into an {@link AmdEvent} and
4917
+ * dispatched to the {@link onAmd} handler. No-op if no handler is registered.
4918
+ *
4919
+ * @param form - Raw form data from the webhook request.
4920
+ */
4921
+ handleAmdEvent(form: Record<string, string>): Promise<{
4922
+ status: number;
4923
+ content: string;
4924
+ contentType: string;
4925
+ }>;
4926
+ /**
4927
+ * Handle a Twilio `recordingStatusCallback` webhook.
4928
+ *
4929
+ * The developer routes the request here (`TACServer` does this automatically
4930
+ * for its `/recording` call-event route). Parsed into a
4931
+ * {@link RecordingEvent} and dispatched to the {@link onRecording} handler.
4932
+ * No-op if no handler is registered.
4933
+ *
4934
+ * @param form - Raw form data from the webhook request.
4935
+ */
4936
+ handleRecordingEvent(form: Record<string, string>): Promise<{
4937
+ status: number;
4938
+ content: string;
4939
+ contentType: string;
4940
+ }>;
4941
+ /**
4942
+ * Hang up a call and clean up its ConversationRelay session.
4943
+ *
4944
+ * Works on `callSid` alone, whether or not a session exists yet. No-ops the
4945
+ * session cleanup if none is tracked.
4946
+ *
4947
+ * Does not throw — hanging up an already-ended call is routine (the callee
4948
+ * hangs up while AMD is still resolving), and handlers shouldn't have to
4949
+ * guard against it.
4950
+ *
4951
+ * @param callSid - Twilio Call SID (from a call event, the outbound result, or
4952
+ * `ConversationSession.callSid`).
4953
+ * @returns True if Twilio accepted the hangup, false if it failed (logged).
4954
+ * Session cleanup runs either way.
4955
+ */
4956
+ endCall(callSid: string): Promise<boolean>;
4957
+ /**
4958
+ * Look up the active voice session for a Twilio Call SID.
4959
+ *
4960
+ * Out-of-band code holding a CallSid — a dashboard route, an operator action,
4961
+ * a call-event handler — can't reach the session-facing methods, which are
4962
+ * keyed by conversation id: the Orchestrator conversation id in orchestrator
4963
+ * mode, the CallSid only in ConversationRelay-only mode.
4964
+ *
4965
+ * Relay-only mode creates the session on the first prompt; orchestrated
4966
+ * mode creates it when the lookup started at setup finishes, so it may
4967
+ * exist before the caller speaks — including before `onAmd` fires. Treat it
4968
+ * as racy and hang up with {@link endCall}, which needs no session.
4969
+ *
4970
+ * At the other end, orchestrator mode keeps the session until Conversation
4971
+ * Orchestrator's CLOSED webhook, so it outlives the call and `onCallStatus` /
4972
+ * `onRecording` do resolve. Relay-only mode tears down on the
4973
+ * ConversationRelay callback instead, which races them.
4974
+ *
4975
+ * @example
4976
+ * ```typescript
4977
+ * async function nudge(callSid: string): Promise<void> {
4978
+ * const session = voiceChannel.getConversationSessionByCallSid(callSid);
4979
+ * if (session) {
4980
+ * await voiceChannel.sendResponse(session.conversationId, 'Still there?');
4981
+ * }
4982
+ * }
4983
+ * ```
4984
+ *
4985
+ * @param callSid - Twilio Call SID, e.g. from
4986
+ * `InitiateVoiceConversationResult.callSid` or a call event.
4987
+ * @returns The session, or `undefined` — not created yet, the call ended, or
4988
+ * it landed on another instance (see the horizontal-scaling note in
4989
+ * CLAUDE.md).
4990
+ */
4991
+ getConversationSessionByCallSid(callSid: string): ConversationSession | undefined;
4992
+ /**
4993
+ * Narrow `provider` to the ConversationRelay implementation for the
4994
+ * ConversationRelay-only forwarders on this channel.
4995
+ *
4996
+ * Throws whenever a consumer supplies a non-ConversationRelay provider, which
4997
+ * is the point of the guard. The provider callback used to narrow here too; it
4998
+ * now rides {@link VoiceProvider.handleTwilioProviderCallback}'s
4999
+ * base-compatible signature instead, which is the eventual shape for these
5000
+ * forwarders.
5001
+ *
5002
+ * @throws {Error} if this channel's provider is not ConversationRelay-based.
5003
+ */
5004
+ private requireConversationRelayProvider;
5005
+ /**
5006
+ * Start tracking a streaming task for a conversation
5007
+ *
5008
+ * @param conversationId - The conversation ID
5009
+ * @returns The stream task with its AbortController
5010
+ */
5011
+ startStreamTask(conversationId: ConversationId): StreamTask;
5012
+ /**
5013
+ * Cancel an active streaming task
5014
+ *
5015
+ * @param conversationId - The conversation ID
5016
+ * @returns true if a task was cancelled, false otherwise
5017
+ */
5018
+ cancelStreamTask(conversationId: ConversationId): boolean;
5019
+ /**
5020
+ * Complete a streaming task (remove from tracking)
5021
+ *
5022
+ * @param conversationId - The conversation ID
5023
+ */
5024
+ completeStreamTask(conversationId: ConversationId): void;
5025
+ /**
5026
+ * Check if a stream task is active
5027
+ *
5028
+ * @param conversationId - The conversation ID
5029
+ * @returns true if an active task exists
5030
+ */
5031
+ hasActiveStreamTask(conversationId: ConversationId): boolean;
5032
+ /**
5033
+ * Generate TwiML to connect a call to ConversationRelay. Delegates to
5034
+ * {@link ConversationRelayProvider.connectConversationRelay}, which validates
5035
+ * the configuration with Zod before generating TwiML.
5036
+ *
5037
+ * @param config - ConversationRelay configuration (url, transcription, TTS, etc.)
5038
+ * @param options - Optional settings for parameters and the Connect verb
5039
+ * @returns TwiML XML string
5040
+ * @throws {Error} if config validation fails, or if this channel's provider is
5041
+ * not ConversationRelay-based.
5042
+ */
5043
+ connectConversationRelay(config: ConversationRelayConfig, options?: {
5044
+ parameters?: CustomParameters;
5045
+ actionUrl?: string;
5046
+ }): string;
5047
+ /**
5048
+ * Cleanup channel state on shutdown
5049
+ *
5050
+ * Note: WebSocket connections are managed by the server and closed there.
5051
+ * This method only cleans up internal channel state.
5052
+ */
5053
+ shutdown(): void;
5054
+ }
5055
+
5056
+ /**
5057
+ * Common construction and option-layering helpers shared by every provider's
5058
+ * TwiML builder.
5059
+ *
5060
+ * Subclasses take `TACConfig` and their provider's channel config wholesale
5061
+ * (not individual derived values) so a later change to either — a new field, a
5062
+ * new default — is a change to the builder alone, not a change to what
5063
+ * `VoiceChannel` has to compute and hand over.
5064
+ *
5065
+ * @internal
5066
+ */
5067
+ declare abstract class TwiMLBuilderBase<TChannelConfig = unknown> {
5068
+ protected readonly tacConfig: TACConfig;
5069
+ protected readonly channelConfig: TChannelConfig;
5070
+ protected readonly logger: Logger;
5071
+ constructor(tacConfig: TACConfig, channelConfig: TChannelConfig, logger: Logger);
5072
+ /**
5073
+ * Apply fields explicitly present on `source` onto `target`, except those
5074
+ * named in `skip`.
5075
+ *
5076
+ * Nested objects, arrays, and dicts replace wholesale — there's no per-key
5077
+ * merging.
5078
+ *
5079
+ * "Explicitly present" is detected via key presence (`Object.keys`), which
5080
+ * mirrors Python's `model_fields_set`: a key set to `undefined` is still
5081
+ * "present" and overrides lower layers, while an absent key falls through.
5082
+ */
5083
+ protected overlayFields(target: Record<string, unknown>, source: Record<string, unknown>, skip?: readonly string[]): void;
5084
+ /**
5085
+ * The error thrown when no layer and no `TACConfig`-derived default supplies
5086
+ * a WebSocket URL. `caller` names the API the developer actually called.
5087
+ */
5088
+ protected missingWebsocketUrlError(caller: string): Error;
5089
+ /**
5090
+ * The WebSocket URL derived from `TACConfig.voicePublicDomain` +
5091
+ * `TACConfig.voiceWebsocketPath`, or undefined when `voicePublicDomain` is
5092
+ * unset.
5093
+ */
5094
+ protected defaultWebsocketUrl(): string | undefined;
5095
+ /**
5096
+ * Resolve the default `<Connect action=...>` cleanup URL from
5097
+ * `TACConfig.voicePublicDomain` + `TACConfig.voiceActionPath`.
5098
+ *
5099
+ * Returns undefined if `voicePublicDomain` isn't set; that's fine because
5100
+ * actionUrl has higher-priority layers (customizer, twimlOptions, Studio
5101
+ * handoff) above this fallback.
5102
+ */
5103
+ protected defaultActionUrl(): string | undefined;
5104
+ }
5105
+
5106
+ /**
5107
+ * The slice of a Media Streams provider's config this builder reads. Declared
5108
+ * structurally rather than importing the provider's config class, so the
5109
+ * builder does not depend on which Media Streams provider owns it.
5110
+ */
5111
+ interface MediaStreamsTwiMLBuilderConfig {
5112
+ defaultTwimlOptions?: VoiceTwiMLOptionsMediaStreams | undefined;
5113
+ }
5114
+ /**
5115
+ * Generate TwiML that connects the call to a bidirectional Media Stream.
5116
+ *
5117
+ * See https://www.twilio.com/docs/voice/twiml/stream for the `<Stream>` verb.
5118
+ *
5119
+ * The WebSocket URL may be passed positionally or as `options.websocketUrl`
5120
+ * (positional wins when both are given), so a caller can pass everything in one
5121
+ * object: `generateStreamTwiml(undefined, { websocketUrl: ... })`.
5122
+ *
5123
+ * @param websocketUrl - Public `wss://` URL of the WebSocket endpoint Twilio
5124
+ * should stream call audio to (the `<Stream url=...>` attribute). Optional if
5125
+ * `options.websocketUrl` is set.
5126
+ * @param options - Optional Media Streams TwiML options.
5127
+ * @returns TwiML XML string ready to return to Twilio.
5128
+ * @throws {Error} if no WebSocket URL is provided via either source.
5129
+ */
5130
+ declare function generateStreamTwiml(websocketUrl?: string, options?: VoiceTwiMLOptionsMediaStreams): string;
5131
+ /** Per-call inputs to {@link TwiMLBuilderMediaStreams.build}. */
5132
+ interface BuildStreamTwiMLInputs {
5133
+ /**
5134
+ * Per-call overrides from the host owning the route (e.g. a per-call
5135
+ * `websocketUrl` with an affinity token). Lowest of the option layers.
5136
+ */
5137
+ host?: VoiceTwiMLOptionsMediaStreams | undefined;
5138
+ /**
5139
+ * Per-call overrides — the `onInboundCallTwiml` customizer's output for
5140
+ * inbound, or `InitiateVoiceConversationOptions.twimlOptions` for outbound.
5141
+ * Highest layer.
5142
+ */
5143
+ perCall?: VoiceTwiMLOptionsMediaStreams | undefined;
5144
+ /**
5145
+ * Dedicated per-call WebSocket override that wins over any `websocketUrl`
5146
+ * coming through the option layers. Used by outbound, which takes it as its
5147
+ * own argument.
5148
+ */
5149
+ websocketUrl?: string | undefined;
5150
+ }
5151
+ /**
5152
+ * Builds the TwiML for a Media Streams call, owning the layering and WebSocket
5153
+ * URL resolution so the provider doesn't have to.
5154
+ */
5155
+ declare class TwiMLBuilderMediaStreams extends TwiMLBuilderBase<MediaStreamsTwiMLBuilderConfig> {
5156
+ /**
5157
+ * Build the TwiML XML for one call.
5158
+ *
5159
+ * TwiML fields are merged per-field, highest precedence first:
5160
+ * 1. `perCall` — the `onInboundCallTwiml` customizer's output for inbound,
5161
+ * or `InitiateVoiceConversationOptions.twimlOptions` for outbound
5162
+ * 2. the provider config's `defaultTwimlOptions` — channel-wide defaults
5163
+ * 3. `host` — per-call transport facts supplied by the host
5164
+ * 4. TAC defaults: the WebSocket URL derived from
5165
+ * `TACConfig.voicePublicDomain` + `voiceWebsocketPath`
5166
+ *
5167
+ * @param caller - Name of the calling method, used in the "no WebSocket URL"
5168
+ * error so it points at the API the developer actually called.
5169
+ * @param options - Per-call option layers and WebSocket override.
5170
+ * @throws {Error} if no layer and no `TACConfig`-derived default supplies a
5171
+ * WebSocket URL.
5172
+ */
5173
+ build(caller: string, options?: BuildStreamTwiMLInputs): string;
5174
+ /**
5175
+ * Layer TwiML options, lowest precedence first: `host` →
5176
+ * `defaultTwimlOptions` → `perCall`.
5177
+ *
5178
+ * `customParameters` replaces wholesale when set at a higher-priority layer —
5179
+ * there's no per-key merging.
5180
+ */
5181
+ protected buildTwimlOptions(host: VoiceTwiMLOptionsMediaStreams | undefined, perCall: VoiceTwiMLOptionsMediaStreams | undefined): VoiceTwiMLOptionsMediaStreams;
5182
+ }
5183
+
5184
+ /** Options accepted by {@link MediaStreamsProviderConfig}. */
5185
+ interface MediaStreamsProviderConfigOptions extends BaseChannelOptions {
5186
+ /**
5187
+ * Static `VoiceTwiMLOptionsMediaStreams` applied to every inbound call.
5188
+ * Per-call customization is registered via
5189
+ * `VoiceChannel.onInboundCallTwiml(...)`, which takes precedence over this.
5190
+ */
5191
+ defaultTwimlOptions?: VoiceTwiMLOptionsMediaStreams;
5192
+ }
5193
+ /**
5194
+ * Base configuration for a Media Streams (`<Connect><Stream>`) provider.
5195
+ *
5196
+ * Holds the transport-level settings every Media Streams provider shares,
5197
+ * independent of which model or protocol runs over the stream.
5198
+ */
5199
+ declare class MediaStreamsProviderConfig extends VoiceProviderConfig {
5200
+ /**
5201
+ * Static `VoiceTwiMLOptionsMediaStreams` applied to every inbound call.
5202
+ * Per-call customization is registered via
5203
+ * `VoiceChannel.onInboundCallTwiml(...)`, which takes precedence over this.
5204
+ */
5205
+ readonly defaultTwimlOptions?: VoiceTwiMLOptionsMediaStreams;
5206
+ constructor(options?: MediaStreamsProviderConfigOptions);
5207
+ }
5208
+
5209
+ /**
5210
+ * TAC Tool class with helper methods for LLM integration
5211
+ *
5212
+ * Matches Python's TACTool dataclass with conversion methods.
5213
+ */
5214
+ declare class TACTool<TParams = unknown, TResult = unknown> {
5215
+ readonly name: string;
5216
+ readonly description: string;
5217
+ readonly parameters: JSONSchema;
5218
+ readonly implementation: ToolFunction<TParams, TResult>;
5219
+ constructor(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>);
5220
+ /**
5221
+ * Convert to OpenAI function calling format
5222
+ */
5223
+ toOpenAIFormat(): OpenAITool;
5224
+ /**
5225
+ * Convert to OpenAI Realtime function calling format.
5226
+ *
5227
+ * Unlike {@link TACTool.toOpenAIFormat} (Chat Completions, which nests the
5228
+ * schema under a `function` key), Realtime's `session.tools` expects the
5229
+ * fields flat on the tool object.
5230
+ */
5231
+ toRealtimeFormat(): OpenAIRealtimeTool;
5232
+ /**
5233
+ * Convert to Anthropic tool calling format
5234
+ */
5235
+ toAnthropicFormat(): AnthropicTool;
5236
+ /**
5237
+ * Convert to JSON string (OpenAI format by default)
5238
+ */
5239
+ toJSON(): string;
5240
+ /**
5241
+ * Convert this tool to an OpenAI Agents SDK `FunctionTool` instance.
5242
+ *
5243
+ * Unlike `toOpenAIFormat` and `toAnthropicFormat` (which return plain
5244
+ * objects consumed by HTTP APIs), the OpenAI Agents SDK dispatches on tool
5245
+ * *type*, so this returns a live `tool(...)` object with an invoke callback
5246
+ * that calls this tool and JSON-encodes the result.
5247
+ *
5248
+ * Requires the `@openai/agents` package:
5249
+ *
5250
+ * npm install @openai/agents
5251
+ *
5252
+ * @returns A FunctionTool ready to pass to `new Agent({ tools: [...] })`.
5253
+ */
5254
+ toOpenAIAgentsSDKTool(): Promise<any>;
5255
+ }
5256
+ /**
5257
+ * Create a tool directly with all parameters
5258
+ *
5259
+ * Simplified approach matching Python's create_tool function.
5260
+ * No builder pattern - just a simple function call.
5261
+ */
5262
+ declare function defineTool<TParams = unknown, TResult = unknown>(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>): TACTool<TParams, TResult>;
5263
+
5264
+ /**
5265
+ * Parameters for memory retrieval tool
5266
+ */
5267
+ interface MemoryRetrievalParams {
5268
+ query?: string;
5269
+ beginDate?: string;
5270
+ endDate?: string;
5271
+ observationsLimit?: number;
5272
+ summariesLimit?: number;
5273
+ communicationsLimit?: number;
5274
+ relevanceThreshold?: number;
5275
+ }
5276
+ /**
5277
+ * Create memory retrieval tool.
5278
+ *
5279
+ * @param memoryClient - Memory client instance (must be initialized with storeId)
5280
+ * @param profileId - Optional profile ID for memory retrieval
5281
+ * @param conversationId - Optional conversation ID for memory retrieval
5282
+ * @param options - Optional overrides for tool metadata.
5283
+ * @param options.name - Tool name exposed to the LLM. Defaults to `retrieve_profile_memory`.
5284
+ * @param options.description - Tool description exposed to the LLM. Defaults to a
5285
+ * generic "retrieve memories" prompt.
5286
+ */
5287
+ declare function createMemoryRetrievalTool(memoryClient: MemoryClient, profileId?: string, conversationId?: string, options?: {
5288
+ name?: string;
5289
+ description?: string;
5290
+ }): TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
5291
+ /**
5292
+ * Create factory function for memory tools
5293
+ *
5294
+ * @param memoryClient - Memory client instance (must be initialized with storeId)
5295
+ */
5296
+ declare function createMemoryTools(memoryClient: MemoryClient): {
5297
+ forProfile: (profileId: string, conversationId?: string) => TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
5298
+ forSession: (profileId?: string, conversationId?: string) => TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
5299
+ };
5300
+
5301
+ /**
5302
+ * Parameters for send message tool
5303
+ */
5304
+ interface SendMessageParams {
5305
+ message: string;
5306
+ metadata?: Record<string, unknown>;
5307
+ }
5308
+ /**
5309
+ * Result from send message tool
5310
+ */
5311
+ interface SendMessageResult {
5312
+ success: boolean;
5313
+ message_id?: string;
5314
+ error?: string;
5315
+ }
5316
+ /**
5317
+ * Create send message tool
5318
+ */
5319
+ declare function createSendMessageTool(channel: BaseChannel, conversationId: ConversationId): TACTool<SendMessageParams, SendMessageResult>;
5320
+ /**
5321
+ * Create factory function for messaging tools
5322
+ */
5323
+ declare function createMessagingTools(): {
5324
+ forConversation: (channel: BaseChannel, conversationId: ConversationId) => TACTool<SendMessageParams, SendMessageResult>;
5325
+ };
5326
+
5327
+ /**
5328
+ * Handoff tool for the Twilio Agent Connect.
5329
+ *
5330
+ * Generic Studio-backed handoff that routes a conversation to a human agent.
5331
+ * Produces a structured HandoffPayload and delivers it as a Twilio Studio
5332
+ * Execution (voice via `<Connect action>`, digital channels via direct POST).
5333
+ */
5334
+
5335
+ /**
5336
+ * Build a HandoffPayload from session context and attributes.
5337
+ *
5338
+ * Useful for custom handoff tools that want TAC's payload shape without
5339
+ * the Studio-specific delivery in `postStudioHandoff`.
5340
+ */
5341
+ declare function buildHandoffPayload(session: ConversationSession, memoryStoreId: string, attributes: Record<string, unknown>): HandoffPayload;
5342
+ /**
5343
+ * POST a handoff payload to a Twilio Studio Flow Executions endpoint.
5344
+ *
5345
+ * Emits the Twilio Studio Executions API wire format: form-encoded
5346
+ * `To` / `From` / `Parameters` fields with HTTP Basic auth.
5347
+ * `Parameters` is a JSON string keyed under `HandoffData` so Studio
5348
+ * can reference it via `{{flow.data.HandoffData.*}}`.
5349
+ */
5350
+ declare function postStudioHandoff(payload: HandoffPayload, session: ConversationSession, options: {
5351
+ handoffUrl: string;
5352
+ fromAddress: string;
5353
+ apiKey: string;
5354
+ apiSecret: string;
5355
+ }): Promise<void>;
5356
+ /**
5357
+ * Result returned by the handoff tool.
5358
+ */
5359
+ interface HandoffResult {
5360
+ status: 'handoff_initiated' | 'handoff_failed';
5361
+ channel: string;
5362
+ error?: string;
5363
+ }
5364
+ interface HandoffParams {
5365
+ reason: string;
5366
+ }
5367
+ /**
5368
+ * Create a handoff tool that delivers in the Twilio Studio Executions API shape.
5369
+ *
5370
+ * The returned tool exposes only `handoff({ reason })` to the LLM. All other
5371
+ * dependencies (TAC instance, session, static attributes) are captured in the
5372
+ * closure.
5373
+ *
5374
+ * On digital channels, the tool POSTs to the Studio Flow Executions endpoint
5375
+ * derived from `tac.getConfig().studioHandoffFlowSid`. For voice channels,
5376
+ * the payload is stored on the session and the voice channel automatically
5377
+ * sends the WS `end` message with `handoffData` after the LLM's final
5378
+ * response is delivered.
5379
+ *
5380
+ * The tool also sets the conversation to INACTIVE and clears status callbacks
5381
+ * to prevent further webhook events from being routed to TAC.
5382
+ *
5383
+ * **Not available in voice-only mode.** This tool requires Conversation
5384
+ * Orchestrator for conversation state management and Conversation Memory for
5385
+ * the handoff payload. In voice-only mode, implement your own handoff by
5386
+ * setting `session.pendingHandoffData` directly — the voice channel will
5387
+ * send the WS `end` message with your payload, and your `<Connect action>`
5388
+ * URL handler can route the call accordingly.
5389
+ *
5390
+ * @throws Error if `tac.getConfig().studioHandoffFlowSid` is unset, if
5391
+ * Conversation Orchestrator is not configured (voice-only mode), or if
5392
+ * the memory store ID was not resolved at startup.
5393
+ */
5394
+ declare function createStudioHandoffTool(tac: TAC, session: ConversationSession, options?: {
5395
+ attributes?: Record<string, unknown>;
5396
+ name?: string;
5397
+ description?: string;
5398
+ }): TACTool<HandoffParams, HandoffResult>;
5399
+
5400
+ /**
5401
+ * Parameters for knowledge search tool (visible to LLM)
5402
+ */
5403
+ interface KnowledgeSearchParams {
5404
+ query: string;
5405
+ }
5406
+ /**
5407
+ * Configuration for knowledge search tool
5408
+ */
5409
+ interface KnowledgeToolConfig {
5410
+ name?: string;
5411
+ description?: string;
5412
+ topK?: number;
5413
+ }
5414
+ /**
5415
+ * Create knowledge search tool with explicit name and description
5416
+ *
5417
+ * @param knowledgeClient - The Knowledge client instance
5418
+ * @param knowledgeBaseId - The knowledge base ID to search
5419
+ * @param config - Configuration with required name and description
5420
+ * @returns TACTool configured for knowledge search
5421
+ */
5422
+ declare function createKnowledgeSearchTool(knowledgeClient: KnowledgeClient, knowledgeBaseId: string, config: {
5423
+ name: string;
5424
+ description: string;
5425
+ topK?: number;
5426
+ }): TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>;
5427
+ /**
5428
+ * Create knowledge search tool with auto-fetched metadata from knowledge base
5429
+ *
5430
+ * This async version fetches the knowledge base metadata to auto-generate
5431
+ * the tool name and description if not provided.
5432
+ *
5433
+ * @param knowledgeClient - The Knowledge client instance
5434
+ * @param knowledgeBaseId - The knowledge base ID to search
5435
+ * @param config - Optional configuration (name/description auto-generated if not provided)
5436
+ * @returns Promise containing TACTool configured for knowledge search
5437
+ */
5438
+ declare function createKnowledgeSearchToolAsync(knowledgeClient: KnowledgeClient, knowledgeBaseId: string, config?: KnowledgeToolConfig): Promise<TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>>;
5439
+ /**
5440
+ * Create factory for knowledge tools
5441
+ *
5442
+ * @param knowledgeClient - The Knowledge client instance
5443
+ * @returns Factory object with methods to create knowledge tools
5444
+ */
5445
+ declare function createKnowledgeTools(knowledgeClient: KnowledgeClient): {
5446
+ forKnowledgeBase: (knowledgeBaseId: string, config: {
5447
+ name: string;
5448
+ description: string;
5449
+ topK?: number;
5450
+ }) => TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>;
5451
+ forKnowledgeBaseAsync: (knowledgeBaseId: string, config?: KnowledgeToolConfig) => Promise<TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>>;
5452
+ };
5453
+
5454
+ /**
5455
+ * Options accepted by {@link MediaStreamsOpenAIProviderConfig}.
5456
+ */
5457
+ interface MediaStreamsOpenAIProviderConfigOptions extends MediaStreamsProviderConfigOptions {
5458
+ /**
5459
+ * OpenAI API key. Defaults to the `OPENAI_API_KEY` environment variable.
5460
+ */
5461
+ openaiApiKey?: string;
5462
+ /**
5463
+ * Executable `TACTool` implementations, looked up by name to run mid-call
5464
+ * tool requests. This alone does not tell the model these tools exist — the
5465
+ * session config sent to OpenAI must separately declare each tool's schema.
5466
+ */
5467
+ tools?: TACTool<never, unknown>[];
5468
+ /**
5469
+ * Session configuration sent to OpenAI once the model connects — used for any
5470
+ * call that doesn't supply its own via
5471
+ * {@link MediaStreamsOpenAIProviderConfigOptions.onInboundCallSessionConfig}
5472
+ * or per-call outbound options.
5473
+ *
5474
+ * If using {@link MediaStreamsOpenAIProviderConfigOptions.tools}, this config
5475
+ * must separately list each tool's schema — it is passed to OpenAI as-is,
5476
+ * with no tool schemas merged in.
5477
+ */
5478
+ defaultSessionConfig?: Record<string, unknown>;
5479
+ /**
5480
+ * Per-inbound-call override for
5481
+ * {@link MediaStreamsOpenAIProviderConfigOptions.defaultSessionConfig},
5482
+ * called with the `TwiMLRequest`. Its return value is used verbatim (not
5483
+ * merged with `defaultSessionConfig`); return `null` to fall back to it.
5484
+ * Outbound calls don't use this — they pass their session config per call.
5485
+ */
5486
+ onInboundCallSessionConfig?: (req: TwiMLRequest) => Promise<Record<string, unknown> | null>;
5487
+ }
5488
+ /**
5489
+ * Base configuration for an OpenAI-backed Media Streams provider.
5490
+ *
5491
+ * Holds what every OpenAI-backed Media Streams provider needs — credentials,
5492
+ * executable tools, and the session config sent when the model connects —
5493
+ * independent of which OpenAI API runs over the stream.
5494
+ */
5495
+ declare class MediaStreamsOpenAIProviderConfig extends MediaStreamsProviderConfig {
5496
+ /** OpenAI API key. Defaults to the `OPENAI_API_KEY` environment variable. */
5497
+ readonly openaiApiKey: string;
5498
+ /**
5499
+ * Executable `TACTool` implementations, looked up by name to run mid-call
5500
+ * tool requests. This alone does not tell the model these tools exist — the
5501
+ * session config sent to OpenAI must separately declare each tool's schema.
5502
+ */
5503
+ readonly tools: TACTool<never, unknown>[];
5504
+ /**
5505
+ * Session configuration sent to OpenAI once the model connects — used for any
5506
+ * call that doesn't supply its own via
5507
+ * {@link MediaStreamsOpenAIProviderConfig.onInboundCallSessionConfig} or
5508
+ * per-call outbound options.
5509
+ *
5510
+ * If using {@link MediaStreamsOpenAIProviderConfig.tools}, this config must
5511
+ * separately list each tool's schema — it is passed to OpenAI as-is, with no
5512
+ * tool schemas merged in.
5513
+ */
5514
+ readonly defaultSessionConfig?: Record<string, unknown>;
5515
+ /**
5516
+ * Per-inbound-call override for
5517
+ * {@link MediaStreamsOpenAIProviderConfig.defaultSessionConfig}, called with
5518
+ * the `TwiMLRequest`. Its return value is used verbatim (not merged with
5519
+ * `defaultSessionConfig`); return `null` to fall back to it. Outbound calls
5520
+ * don't use this — they pass their session config per call.
5521
+ */
5522
+ readonly onInboundCallSessionConfig?: (req: TwiMLRequest) => Promise<Record<string, unknown> | null>;
5523
+ constructor(options?: MediaStreamsOpenAIProviderConfigOptions);
5524
+ }
5525
+
5526
+ /**
5527
+ * Both legs of one call's audio bridge — the Twilio-facing socket and the
5528
+ * model-facing socket — live here together, rather than in two parallel maps
5529
+ * keyed by conversation id that could drift out of sync.
5530
+ *
5531
+ * `streamSid` and `transcript` live on `ConversationSession.metadata` instead,
5532
+ * not here: this map is deleted before `onConversationEnded` fires, so anything
5533
+ * a handler needs to read after the call ends must survive on the session.
5534
+ *
5535
+ * @internal
5536
+ */
5537
+ declare class MediaStreamsOpenAICallState {
5538
+ twilioWs: WebSocket | null;
5539
+ modelWs: WebSocket | null;
5540
+ /**
5541
+ * Resolves `true` once this call's model socket is open and its session
5542
+ * config has been sent, or `false` if that handshake failed. `null` until the
5543
+ * handshake has been started.
5544
+ *
5545
+ * Twilio begins streaming caller audio as soon as the media stream opens,
5546
+ * which is well before the OpenAI handshake completes. Caller audio waits on
5547
+ * this promise rather than being written to a socket that does not exist
5548
+ * yet, so a caller who speaks the instant the call connects is not clipped.
5549
+ * Every frame awaits this same promise, so the frames resume in the order
5550
+ * they arrived.
5551
+ *
5552
+ * It resolves rather than rejects: a failed handshake is reported once, by
5553
+ * the code that opened the socket, not once per waiting frame.
5554
+ */
5555
+ modelReady: Promise<boolean> | null;
5556
+ }
5557
+
5558
+ /**
5559
+ * Identifies this SDK to OpenAI on every WebSocket connection, per OpenAI's
5560
+ * requested User-Agent pattern: [Company/Library name]/[Language] [Version].
5561
+ *
5562
+ * Deliberately unlike the Twilio-facing User-Agent in `clients/base.ts`, which
5563
+ * follows Twilio's own convention instead.
5564
+ */
5565
+ declare const OPENAI_USER_AGENT: string;
5566
+ /**
5567
+ * Shared scaffolding for a {@link VoiceProvider} bridging Twilio Media Streams
5568
+ * to an OpenAI real-time voice API.
5569
+ *
5570
+ * Holds only what's identical across every such provider; each subclass still
5571
+ * owns its own `initiateOutboundConversation`, `handleWebSocket`,
5572
+ * `registerCall`, `connectModel`, {@link dispatchModelEvent},
5573
+ * `handleFunctionCall`, and `cleanupCall`.
5574
+ *
5575
+ * Generic over `TCallState` (bound to `MediaStreamsOpenAICallState`) so
5576
+ * {@link calls} keeps each subclass's own call-state shape instead of widening
5577
+ * to the shared base everywhere it's read.
5578
+ */
5579
+ declare abstract class MediaStreamsOpenAIProvider<TCallState extends MediaStreamsOpenAICallState> extends VoiceProvider {
5580
+ /**
5581
+ * The owning channel's logger, so this provider logs under the same name the
5582
+ * rest of the voice channel does.
5583
+ */
5584
+ protected readonly logger: Logger;
5585
+ /** Executable tools from the config, looked up by the name the model sends. */
5586
+ protected readonly toolsByName: Map<string, TACTool>;
5587
+ /** Per-call transport state, keyed by conversation id. */
5588
+ protected readonly calls: Map<ConversationId, TCallState>;
5589
+ protected readonly config: MediaStreamsOpenAIProviderConfig;
5590
+ protected readonly tacConfig: TACConfig;
5591
+ protected readonly twimlBuilder: TwiMLBuilderMediaStreams;
5592
+ /**
5593
+ * Session config overrides awaiting the call they belong to.
5594
+ *
5595
+ * Inbound entries are keyed by call SID (known when the TwiML webhook is
5596
+ * answered); a subclass keys its outbound entries by whatever token it round
5597
+ * trips through the stream's custom parameters.
5598
+ */
5599
+ protected readonly pendingSessionConfigs: Map<string, Record<string, unknown>>;
5600
+ /**
5601
+ * Expiry timers for the inbound {@link pendingSessionConfigs} entries, keyed
5602
+ * by the same call SID. Each fires once to purge a stash whose Media Stream
5603
+ * never connected; a normal connect cancels it in the subclass's
5604
+ * `registerCall`. Outbound entries are keyed by token instead and are not
5605
+ * tracked here.
5606
+ */
5607
+ private readonly pendingInboundExpiries;
5608
+ constructor(channel: VoiceChannel, tacConfig: TACConfig, config: MediaStreamsOpenAIProviderConfig);
5609
+ /** The Twilio-facing WebSocket for a conversation, if one is tracked. */
5610
+ getWebSocket(conversationId: ConversationId): WebSocket | null;
5611
+ /**
5612
+ * Open a WebSocket and resolve once it is ready to carry traffic.
5613
+ *
5614
+ * Isolated from each subclass's `connectModel` so tests can substitute a
5615
+ * socket without reaching the network.
5616
+ *
5617
+ * A resolved socket always carries at least one `'error'` listener, whatever
5618
+ * the caller does with it next.
5619
+ *
5620
+ * @internal
5621
+ */
5622
+ openModelSocket(url: string, headers: Record<string, string>): Promise<WebSocket>;
5623
+ /**
5624
+ * The transcript captured so far for an in-progress call.
5625
+ *
5626
+ * It lives on `ConversationSession.metadata.transcript`, so once the call
5627
+ * ends and the session is dropped it is no longer reachable here — read it
5628
+ * from the session an `onConversationEnded` handler receives instead.
5629
+ */
5630
+ getTranscript(conversationId: ConversationId): Record<string, string>[];
5631
+ /**
5632
+ * The session config stashed for `key` — a call SID for inbound calls, a
5633
+ * token for outbound ones.
5634
+ *
5635
+ * @internal
5636
+ */
5637
+ peekPendingSessionConfig(key: string): Record<string, unknown> | undefined;
5638
+ /**
5639
+ * How many session config overrides are waiting for their call.
5640
+ *
5641
+ * @internal
5642
+ */
5643
+ pendingSessionConfigCount(): number;
5644
+ /**
5645
+ * Start the clock on an inbound stash, so a call whose Media Stream never
5646
+ * connects cannot strand its override in {@link pendingSessionConfigs} until
5647
+ * shutdown.
5648
+ *
5649
+ * Unref'd: a two-minute timer must not be what keeps the process alive after
5650
+ * the call it belongs to is long over. Re-arming replaces any prior timer for
5651
+ * the same call SID, so a duplicate inbound webhook can't orphan one.
5652
+ */
5653
+ private armInboundConfigExpiry;
5654
+ /**
5655
+ * Stop the clock on an inbound stash, once the call it belongs to has
5656
+ * connected and is about to consume the entry. A no-op for outbound calls,
5657
+ * which key their stash by token and never arm one — the subclass calls this
5658
+ * with the call SID for every `start`, inbound or not.
5659
+ *
5660
+ * @internal
5661
+ */
5662
+ protected cancelInboundConfigExpiry(callSid: string): void;
5663
+ /**
5664
+ * The executable tool the model would run for `name`, if the config supplied
5665
+ * one.
5666
+ *
5667
+ * @internal
5668
+ */
5669
+ peekTool(name: string): TACTool | undefined;
5670
+ /**
5671
+ * Build the `<Connect><Stream>` TwiML for an inbound call.
5672
+ *
5673
+ * TwiML fields are merged per-field, highest precedence first:
5674
+ * 1. Output of the customizer registered via
5675
+ * `VoiceChannel.onInboundCallTwiml(...)`, if configured and
5676
+ * `twimlRequest` is given
5677
+ * 2. `MediaStreamsProviderConfig.defaultTwimlOptions` — channel-wide
5678
+ * defaults
5679
+ * 3. `options.hostTwimlOptions` — per-call transport facts supplied by the
5680
+ * host
5681
+ * 4. TAC defaults: the WebSocket URL derived from
5682
+ * `TACConfig.voicePublicDomain` + `voiceWebsocketPath`
5683
+ *
5684
+ * Also runs `MediaStreamsOpenAIProviderConfig.onInboundCallSessionConfig`, if
5685
+ * set, and stashes its result for the call to pick up once it connects. The
5686
+ * hook runs only after the TwiML builds, so a call that never connects
5687
+ * leaves nothing stashed behind it.
5688
+ *
5689
+ * @param twimlRequest - Parsed Twilio webhook fields for the inbound call.
5690
+ * @param options - Additional per-call inputs.
5691
+ * @param options.hostTwimlOptions - Per-call TwiML supplied by a custom
5692
+ * in-process host.
5693
+ * @throws {TypeError} if either the host options or the customizer's output
5694
+ * is not a `VoiceTwiMLOptionsMediaStreams`.
5695
+ * @throws {Error} if no WebSocket URL can be resolved — none of the TwiML
5696
+ * layers set one and `TACConfig.voicePublicDomain` is unset.
3860
5697
  */
3861
5698
  handleIncomingCall(twimlRequest?: TwiMLRequest, options?: {
3862
- hostTwimlOptions?: TwiMLOptions;
5699
+ hostTwimlOptions?: VoiceTwiMLOptions;
3863
5700
  }): Promise<string>;
3864
5701
  /**
3865
- * Layer TwiML options, lowest precedence first: TAC defaults → `host`
3866
- * (calling host's per-call values) → channel `defaultTwimlOptions` → `perCall`
3867
- * (application customizer output for inbound, or
3868
- * `InitiateVoiceConversationOptions.twimlOptions` for outbound).
5702
+ * Narrow provider-agnostic {@link VoiceTwiMLOptions} to this provider's
5703
+ * concrete shape. `VoiceProvider.handleIncomingCall` is typed against the
5704
+ * base so every provider can accept its own TwiML options, so the Media
5705
+ * Streams shape has to be established at runtime.
5706
+ *
5707
+ * @param value - Options from a caller or the application customizer.
5708
+ * @param caller - Name of the calling method, for the error message.
5709
+ * @param label - What produced `value`, for the error message.
3869
5710
  */
3870
- private buildTwimlOptions;
5711
+ protected narrowTwimlOptions(value: VoiceTwiMLOptions | undefined, caller: string, label: string): VoiceTwiMLOptionsMediaStreams | undefined;
3871
5712
  /**
3872
- * Apply fields explicitly present on `source` onto `target`.
3873
- *
3874
- * Nested objects (`customParameters`), arrays (`languages`), and dicts
3875
- * (`extra`) replace wholesale — there's no per-key merging.
5713
+ * Parse one frame off the model socket and hand it to
5714
+ * {@link dispatchModelEvent}.
3876
5715
  *
3877
- * `actionUrl` is skipped here on purpose — it's resolved once via
3878
- * `resolveActionUrl` looking at every layer at once, and that resolved value
3879
- * is written into `target` before this overlay runs. Letting it through here
3880
- * would let a higher-priority layer that didn't set actionUrl silently clobber
3881
- * a lower layer that did.
5716
+ * A failure here is logged and skipped rather than ending the call: one
5717
+ * malformed delta must not hang up on the caller.
3882
5718
  *
3883
- * "Explicitly present" is detected via key presence (`key in source`), which
3884
- * mirrors Python's `model_fields_set`: a key set to `undefined` is still
3885
- * "present" and overrides lower layers, while an absent key falls through.
5719
+ * @internal
5720
+ */
5721
+ handleModelMessage(conversationId: ConversationId, raw: Buffer | string): Promise<void>;
5722
+ /**
5723
+ * Interpret one event received from the model. Protocol-specific —
5724
+ * implemented by each subclass.
3886
5725
  */
3887
- private overlayFields;
5726
+ protected abstract dispatchModelEvent(conversationId: ConversationId, session: ConversationSession, event: Record<string, unknown>): Promise<void>;
3888
5727
  /**
3889
- * Resolve the TwiML `<Connect action=...>` URL.
5728
+ * Look up a model-requested tool by name, run it, and return its output.
3890
5729
  *
3891
- * Precedence (highest to lowest):
3892
- * 1. application customizer
3893
- * 2. channel `defaultTwimlOptions`
3894
- * 3. `host` (calling host's per-call options)
3895
- * 4. Studio handoff (when `studioHandoffFlowSid` is configured)
3896
- * 5. Channel default — derived from `TACConfig.voicePublicDomain` +
3897
- * `TACConfig.voiceActionPath`.
5730
+ * Errors are returned as part of the output rather than thrown, so a bad
5731
+ * tool call does not kill the call.
3898
5732
  *
3899
- * User-expressed intent (Studio handoff is configured explicitly on
3900
- * `TACConfig`) beats the SDK's generated cleanup default.
5733
+ * @internal
5734
+ */
5735
+ runToolCall(conversationId: ConversationId, name: string, argumentsJson: unknown): Promise<unknown>;
5736
+ /** Write one event to this call's model socket, if it still has one. */
5737
+ protected modelSend(conversationId: ConversationId, payload: Record<string, unknown>): void;
5738
+ /** Write one message to this call's Twilio socket, if it still has one. */
5739
+ protected twilioSend(conversationId: ConversationId, payload: Record<string, unknown>): void;
5740
+ /**
5741
+ * Always throws: the model streams its reply as audio straight to Twilio, so
5742
+ * this transport has no text response to send.
5743
+ */
5744
+ sendResponse(_conversationId: ConversationId, _message: string, _metadata?: Record<string, unknown>): Promise<void>;
5745
+ /**
5746
+ * Drop this provider's Media Streams transport state on channel shutdown.
3901
5747
  *
3902
- * Explicit `actionUrl: undefined` on a layer (key present, value undefined)
3903
- * suppresses `<Connect action=...>` entirely — all lower layers are skipped.
3904
- * `actionUrl` left absent (key not present) falls through to the next layer.
5748
+ * Note: WebSocket connections are managed by the server and closed there.
5749
+ * This method only cleans up internal provider state — including session
5750
+ * config overrides stashed for calls that were placed but never connected.
5751
+ */
5752
+ shutdown(): void;
5753
+ }
5754
+
5755
+ /**
5756
+ * Options accepted by {@link OpenAIRealtimeProviderConfig}.
5757
+ */
5758
+ interface OpenAIRealtimeProviderConfigOptions extends MediaStreamsOpenAIProviderConfigOptions {
5759
+ /**
5760
+ * Executable `TACTool` implementations, looked up by name to run mid-call
5761
+ * tool requests. This alone does not tell the model these tools exist — also
5762
+ * add each tool's `toRealtimeFormat()` schema to
5763
+ * {@link OpenAIRealtimeProviderConfigOptions.defaultSessionConfig}'s `tools`
5764
+ * entry.
3905
5765
  */
3906
- private resolveActionUrl;
5766
+ tools?: TACTool<never, unknown>[];
3907
5767
  /**
3908
- * Overlay `perCall` onto `VoiceChannelConfig.defaultCallOptions`.
5768
+ * If set, sent verbatim as `response.create`'s `response` payload when the
5769
+ * call connects — e.g. `{ instructions: 'Hi there!' }`. No SDK-added wrapping
5770
+ * text or language assumption.
5771
+ */
5772
+ welcomeGreetingResponse?: Record<string, unknown>;
5773
+ /**
5774
+ * The `session.update` payload's `session` body, sent once the model connects
5775
+ * — used for any call that doesn't supply its own via
5776
+ * {@link OpenAIRealtimeProviderConfigOptions.onInboundCallSessionConfig} or
5777
+ * `InitiateVoiceConversationOptionsOpenAIRealtime`.
3909
5778
  *
3910
- * Per-field via key presence, the same convention {@link overlayFields} uses
3911
- * for TwiML options — so a per-call `{ machineDetection: undefined }`
3912
- * explicitly clears the channel default rather than falling through to it.
5779
+ * See
5780
+ * https://developers.openai.com/api/reference/resources/realtime/client-events#session.update
5781
+ * for the schema. If using {@link OpenAIRealtimeProviderConfigOptions.tools},
5782
+ * its `tools` entry must separately list each tool's `toRealtimeFormat()`
5783
+ * schema — this config is passed to OpenAI as-is, with no tool schemas merged
5784
+ * in.
5785
+ */
5786
+ defaultSessionConfig?: Record<string, unknown>;
5787
+ /**
5788
+ * Per-inbound-call override for
5789
+ * {@link OpenAIRealtimeProviderConfigOptions.defaultSessionConfig}, called
5790
+ * with the `TwiMLRequest`. Its return value is used verbatim (not merged with
5791
+ * `defaultSessionConfig`); return `null` to fall back to it. Outbound calls
5792
+ * don't use this — see `InitiateVoiceConversationOptionsOpenAIRealtime`.
5793
+ */
5794
+ onInboundCallSessionConfig?: (req: TwiMLRequest) => Promise<Record<string, unknown> | null>;
5795
+ }
5796
+ /**
5797
+ * Configuration for `OpenAIRealtimeProvider`.
5798
+ */
5799
+ declare class OpenAIRealtimeProviderConfig extends MediaStreamsOpenAIProviderConfig {
5800
+ /**
5801
+ * Executable `TACTool` implementations, looked up by name to run mid-call
5802
+ * tool requests. This alone does not tell the model these tools exist — also
5803
+ * add each tool's `toRealtimeFormat()` schema to
5804
+ * {@link OpenAIRealtimeProviderConfig.defaultSessionConfig}'s `tools` entry.
5805
+ */
5806
+ readonly tools: TACTool<never, unknown>[];
5807
+ /**
5808
+ * If set, sent verbatim as `response.create`'s `response` payload when the
5809
+ * call connects — e.g. `{ instructions: 'Hi there!' }`. No SDK-added wrapping
5810
+ * text or language assumption.
5811
+ */
5812
+ readonly welcomeGreetingResponse?: Record<string, unknown>;
5813
+ /**
5814
+ * The `session.update` payload's `session` body, sent once the model connects
5815
+ * — used for any call that doesn't supply its own via
5816
+ * {@link OpenAIRealtimeProviderConfig.onInboundCallSessionConfig} or
5817
+ * `InitiateVoiceConversationOptionsOpenAIRealtime`.
3913
5818
  *
3914
- * The result is always validated, for two reasons: a combination only
3915
- * reachable by layering — per-call clearing `machineDetection` while the
3916
- * default set `asyncAmd` — must still fail instead of reaching Twilio, and
3917
- * `VoiceChannelConfig` is a plain interface, so `defaultCallOptions` has had
3918
- * no runtime validation of its own.
5819
+ * See
5820
+ * https://developers.openai.com/api/reference/resources/realtime/client-events#session.update
5821
+ * for the schema. If using {@link OpenAIRealtimeProviderConfig.tools}, its
5822
+ * `tools` entry must separately list each tool's `toRealtimeFormat()` schema
5823
+ * — this config is passed to OpenAI as-is, with no tool schemas merged in.
3919
5824
  */
3920
- private mergeCallOptions;
5825
+ readonly defaultSessionConfig?: Record<string, unknown>;
3921
5826
  /**
3922
- * Build the extra arguments for `client.calls.create`.
5827
+ * Per-inbound-call override for
5828
+ * {@link OpenAIRealtimeProviderConfig.defaultSessionConfig}, called with the
5829
+ * `TwiMLRequest`. Its return value is used verbatim (not merged with
5830
+ * `defaultSessionConfig`); return `null` to fall back to it. Outbound calls
5831
+ * don't use this — see `InitiateVoiceConversationOptionsOpenAIRealtime`.
5832
+ */
5833
+ readonly onInboundCallSessionConfig?: (req: TwiMLRequest) => Promise<Record<string, unknown> | null>;
5834
+ constructor(options?: OpenAIRealtimeProviderConfigOptions);
5835
+ createProvider(channel: VoiceChannel, tacConfig: TACConfig): VoiceProvider;
5836
+ }
5837
+
5838
+ /**
5839
+ * Per-call barge-in bookkeeping.
5840
+ *
5841
+ * For every delta that carries an `item_id`, `currentItemAudioMs` is never
5842
+ * more than the duration of audio actually sent to Twilio for
5843
+ * `lastAssistantItem`: it comes from delta byte counts rather than a
5844
+ * wall-clock estimate, floored per delta, so it can understate by up to a
5845
+ * millisecond per delta. `conversation.item.truncate` rejects an `audioEndMs`
5846
+ * beyond the item's real content, so understating is the safe direction.
5847
+ *
5848
+ * `responseActive` tracks whether a response is still being generated (set on
5849
+ * `response.created`, cleared on `response.done` or once barge-in cancels it) —
5850
+ * `response.cancel` with nothing in flight is itself an error event, so this
5851
+ * gates whether to send it.
5852
+ *
5853
+ * `mutedItemId` is the assistant item truncated by the last barge-in —
5854
+ * `response.output_audio.delta` events whose `item_id` matches it are dropped
5855
+ * as stale audio for a reply the caller already talked over. It is never
5856
+ * cleared; the next barge-in overwrites it.
5857
+ *
5858
+ * @internal
5859
+ */
5860
+ declare class BargeInState {
5861
+ lastAssistantItem: string | null;
5862
+ currentItemAudioMs: number;
5863
+ mutedItemId: string | null;
5864
+ responseActive: boolean;
5865
+ }
5866
+ /**
5867
+ * Per-call bookkeeping the OpenAI Realtime provider needs beyond
5868
+ * `ConversationSession` and the sockets its base class holds.
5869
+ *
5870
+ * @internal
5871
+ */
5872
+ declare class CallState$1 extends MediaStreamsOpenAICallState {
5873
+ /**
5874
+ * Tail of this call's model-event chain: each incoming OpenAI Realtime event
5875
+ * is appended to it rather than dispatched on arrival.
3923
5876
  *
3924
- * Layers, highest precedence first: this call's `callOptions`,
3925
- * `VoiceChannelConfig.defaultCallOptions`, then callback URLs derived from
3926
- * `voicePublicDomain` + `voiceCallEventPath`.
5877
+ * The Python SDK reads model events in a sequential loop, so event N is fully
5878
+ * handled before N+1 is even read. `ws` delivers each event on its own
5879
+ * `'message'` emission with nothing serializing them, so without this chain a
5880
+ * `response.output_audio.delta` could advance the barge-in bookkeeping while
5881
+ * dispatch is suspended on the `handleFunctionCall` await, producing a
5882
+ * truncate that overruns the item it names.
5883
+ */
5884
+ modelEvents: Promise<void>;
5885
+ readonly bargeIn: BargeInState;
5886
+ }
5887
+
5888
+ /**
5889
+ * The audio format both directions of a call must use.
5890
+ *
5891
+ * Twilio Media Streams always sends and expects 8kHz G.711 u-law — see
5892
+ * https://www.twilio.com/docs/voice/media-streams/websocket-messages. Not
5893
+ * configurable. No `rate` key: Realtime's `session.audio.*.format` schema
5894
+ * rejects it as unknown, since g711 is inherently fixed-rate.
5895
+ */
5896
+ declare const TWILIO_AUDIO_FORMAT_FOR_REALTIME: {
5897
+ readonly type: "audio/pcmu";
5898
+ };
5899
+ /**
5900
+ * A {@link VoiceProvider} bridging Twilio Media Streams to OpenAI's Realtime
5901
+ * API.
5902
+ *
5903
+ * Twilio streams call audio to TAC's own WebSocket via `<Connect><Stream>`, and
5904
+ * this provider relays it to and from a second WebSocket it opens to OpenAI's
5905
+ * Realtime API.
5906
+ *
5907
+ * ```ts
5908
+ * const channel = new VoiceChannel(
5909
+ * tac,
5910
+ * new OpenAIRealtimeProviderConfig({ defaultSessionConfig: { instructions: '...' } })
5911
+ * );
5912
+ * ```
5913
+ */
5914
+ declare class OpenAIRealtimeProvider extends MediaStreamsOpenAIProvider<CallState$1> {
5915
+ /** @internal */
5916
+ get providerId(): string;
5917
+ /**
5918
+ * The Realtime-specific config this provider was built with.
3927
5919
  *
3928
- * A URL is derived only when its handler is registered. That's a deliberate
3929
- * deviation from `websocketUrl` / `actionUrl`, which derive unconditionally:
3930
- * those are load-bearing, so a wrong one fails loudly on the first call,
3931
- * whereas an unwanted call-event URL fails as silent 11200 alerts for a
3932
- * feature nobody asked for. Set the URLs in `defaultCallOptions` when TAC
3933
- * isn't serving the routes.
5920
+ * `declare`: `target: ES2022` implies `useDefineForClassFields`, so a plain
5921
+ * redeclaration would emit a field definition that runs after `super()` and
5922
+ * overwrite the value the base constructor assigned with `undefined`. This
5923
+ * exists only to narrow the base's `MediaStreamsOpenAIProviderConfig` to the
5924
+ * Realtime shape `connectModel` reads `welcomeGreetingResponse` from.
5925
+ *
5926
+ * No `override`: TypeScript rejects it alongside `declare` (TS1243), and
5927
+ * `noImplicitOverride` does not require it for a `declare`d field.
3934
5928
  */
3935
- private buildCallParams;
5929
+ protected readonly config: OpenAIRealtimeProviderConfig;
5930
+ constructor(channel: VoiceChannel, tacConfig: TACConfig, config: OpenAIRealtimeProviderConfig);
5931
+ get channelName(): string;
3936
5932
  /**
3937
- * Initiate an outbound voice conversation
5933
+ * Initiate an outbound voice conversation.
3938
5934
  *
3939
- * Places an outbound call with inline TwiML that connects to ConversationRelay.
3940
- * The conversationConfiguration attribute tells CO to create and manage the
3941
- * conversation during passive hydration. The session is initialized when the
3942
- * background callSid lookup started at WebSocket setup finds it.
5935
+ * Places an outbound call with inline TwiML that connects to a Media Stream.
5936
+ * Unlike inbound, there is no local session yet at this point — one is
5937
+ * created when Twilio's WebSocket `start` event arrives.
3943
5938
  *
3944
- * TwiML fields are merged per-field, highest precedence first:
3945
- * 1. `options.twimlOptions` — per-call overrides
3946
- * 2. `VoiceChannelConfig.defaultTwimlOptions` — channel-wide defaults
3947
- * 3. TAC defaults: welcome greeting, `conversationConfiguration` from
3948
- * `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
3949
- * derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
5939
+ * TwiML fields are merged per-field — see
5940
+ * {@link TwiMLBuilderMediaStreams.build}. The WebSocket URL is derived from
5941
+ * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` unless
5942
+ * overridden per-call via `options.websocketUrl`.
3950
5943
  *
3951
- * Calls-API parameters merge the same way:
3952
- * 1. `options.callOptions` — per-call overrides
3953
- * 2. `VoiceChannelConfig.defaultCallOptions` — channel-wide defaults
3954
- * 3. Callback URLs derived from `TACConfig.voicePublicDomain` +
3955
- * `voiceCallEventPath`, for handlers that are registered
5944
+ * Pass `InitiateVoiceConversationOptionsOpenAIRealtime` with `sessionConfig`
5945
+ * set to override `OpenAIRealtimeProviderConfig.defaultSessionConfig` for
5946
+ * this call.
3956
5947
  *
3957
- * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
3958
- * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
3959
- * `options.websocketUrl`.
5948
+ * @param options - Outbound call options, validated in full against
5949
+ * `InitiateVoiceConversationOptionsOpenAIRealtimeSchema`.
5950
+ * @throws {TypeError} if `options` is not a valid
5951
+ * `InitiateVoiceConversationOptionsOpenAIRealtime` — including an unknown
5952
+ * key, a missing `to`, or a `twimlOptions` that is not a
5953
+ * `VoiceTwiMLOptionsMediaStreams`.
5954
+ * @throws {Error} if no WebSocket URL can be resolved — neither
5955
+ * `options.websocketUrl` nor any TwiML layer sets one and
5956
+ * `TACConfig.voicePublicDomain` is unset.
3960
5957
  */
3961
- initiateOutboundConversation(options: InitiateVoiceConversationOptions): Promise<InitiateVoiceConversationResult>;
5958
+ initiateOutboundConversation(options: InitiateVoiceConversationOptions | InitiateVoiceConversationOptionsOpenAIRealtime): Promise<InitiateVoiceConversationResult>;
3962
5959
  /**
3963
- * Handle ConversationRelay callback from Twilio. Cleans up on call completion
3964
- * in voice-only mode; in orchestrated mode the CO webhook owns cleanup.
5960
+ * Drive one Twilio Media Stream connection from `start` to disconnect.
3965
5961
  *
3966
- * @param payload - Callback payload from Twilio
3967
- * @returns Response with status, content, and content type
3968
- */
3969
- handleConversationRelayCallback(payload: ConversationRelayCallbackPayload): Promise<{
3970
- status: number;
3971
- content: string;
3972
- contentType: string;
3973
- }>;
3974
- /**
3975
- * Whether a call-webhook payload belongs to the configured account.
5962
+ * Twilio's `start` event names the call, which opens the matching OpenAI
5963
+ * Realtime socket; from then on caller audio is relayed to the model and the
5964
+ * model's audio back to Twilio, until either side goes away. Whichever leg
5965
+ * closes first takes the other down with it, so a caller is never left
5966
+ * connected to silence.
3976
5967
  *
3977
- * Twilio signature validation already gates the route; this is defense in
3978
- * depth. A payload with no `AccountSid` is allowed through.
5968
+ * Twilio streams audio without waiting for the OpenAI socket to finish
5969
+ * connecting, so audio that arrives during that handshake is held and
5970
+ * forwarded, in order, once the model is ready — a caller who speaks the
5971
+ * instant the call connects is heard in full.
3979
5972
  *
3980
- * Subaccounts: events carry the SID the call was placed on, so configure TAC
3981
- * with that account or its events get dropped here.
5973
+ * Called by `VoiceChannel.handleWebSocketConnection`; hosts serve the socket
5974
+ * rather than calling this directly.
5975
+ *
5976
+ * @param ws - The accepted Twilio-facing WebSocket.
3982
5977
  */
3983
- private callEventAccountOk;
5978
+ handleWebSocket(ws: WebSocket): void;
3984
5979
  /**
3985
- * Parse a call-event webhook form and dispatch it to its handler.
5980
+ * Handle Twilio's `start` event: track the call and open its session.
3986
5981
  *
3987
- * Returns 400 when the payload can't be parsed (no `CallSid`) or the handler
3988
- * throws — better than handing Twilio a 200 for an event that wasn't
3989
- * processed. Everything else, including no handler registered and an
3990
- * account mismatch, is a 200 no-op.
5982
+ * @param start - The event's `start` body, parsed against
5983
+ * `StreamStartMessageSchema`.
5984
+ * @param ws - The Twilio-facing socket this call arrived on.
5985
+ * @returns The conversation id — which is the call SID — and the call's
5986
+ * freshly tracked transport state.
3991
5987
  */
3992
- private dispatchCallEvent;
5988
+ private registerCall;
3993
5989
  /**
3994
- * Handle a Twilio `statusCallback` webhook.
3995
- *
3996
- * The developer routes the request here (`TACServer` does this automatically
3997
- * for its `/status` call-event route). Parsed into a {@link CallStatusEvent}
3998
- * and dispatched to the {@link onCallStatus} handler. No-op if no handler is
3999
- * registered.
5990
+ * Open this call's OpenAI Realtime socket and send its session config.
4000
5991
  *
4001
- * @param form - Raw form data from the webhook request.
5992
+ * @internal
4002
5993
  */
4003
- handleCallStatusEvent(form: Record<string, string>): Promise<{
4004
- status: number;
4005
- content: string;
4006
- contentType: string;
4007
- }>;
5994
+ connectModel(conversationId: ConversationId): Promise<void>;
4008
5995
  /**
4009
- * Handle a Twilio `asyncAmdStatusCallback` webhook.
4010
- *
4011
- * The developer routes the request here (`TACServer` does this automatically
4012
- * for its `/amd` call-event route). Parsed into an {@link AmdEvent} and
4013
- * dispatched to the {@link onAmd} handler. No-op if no handler is registered.
5996
+ * The validated session config for this call: its own stashed override if it
5997
+ * has one, else the channel-wide default.
4014
5998
  *
4015
- * @param form - Raw form data from the webhook request.
5999
+ * @throws {Error} if neither exists, if it has no `model`, or if either audio
6000
+ * direction is set to a format Twilio can't carry.
4016
6001
  */
4017
- handleAmdEvent(form: Record<string, string>): Promise<{
4018
- status: number;
4019
- content: string;
4020
- contentType: string;
4021
- }>;
6002
+ private resolveSessionConfig;
4022
6003
  /**
4023
- * Handle a Twilio `recordingStatusCallback` webhook.
4024
- *
4025
- * The developer routes the request here (`TACServer` does this automatically
4026
- * for its `/recording` call-event route). Parsed into a
4027
- * {@link RecordingEvent} and dispatched to the {@link onRecording} handler.
4028
- * No-op if no handler is registered.
6004
+ * Wire up the model socket: dispatch its events, and tear the call down when
6005
+ * it goes away.
4029
6006
  *
4030
- * @param form - Raw form data from the webhook request.
6007
+ * The Python SDK races its two read loops so the Twilio leg dies with the
6008
+ * model leg; `ws` is event-driven, so the same guarantee is a close/error
6009
+ * handler instead. Python's sequential read loop also handles each model
6010
+ * event to completion before reading the next, which `ws` does not — see
6011
+ * {@link CallState.modelEvents} for the chain that restores it.
4031
6012
  */
4032
- handleRecordingEvent(form: Record<string, string>): Promise<{
4033
- status: number;
4034
- content: string;
4035
- contentType: string;
4036
- }>;
6013
+ private attachModelHandlers;
4037
6014
  /**
4038
- * Hang up a call and clean up its ConversationRelay session.
4039
- *
4040
- * Works on `callSid` alone, whether or not a session exists yet. No-ops the
4041
- * session cleanup if none is tracked.
6015
+ * Hang up the Twilio leg because the model leg is gone, then clean up. A
6016
+ * no-op once the call has already been cleaned up, so both the model socket's
6017
+ * `close` and its `error` can call it.
6018
+ */
6019
+ private endCallFromModel;
6020
+ /** Apply one parsed OpenAI Realtime event to the call. */
6021
+ protected dispatchModelEvent(conversationId: ConversationId, session: ConversationSession, event: Record<string, unknown>): Promise<void>;
6022
+ /** Record one turn on the session's running transcript. */
6023
+ private appendTranscript;
6024
+ /**
6025
+ * The caller started talking. Cancel any response still generating, truncate
6026
+ * the model's memory of the last reply at the point actually heard, then
6027
+ * clear Twilio's buffered audio so playback stops immediately.
4042
6028
  *
4043
- * Does not throw — hanging up an already-ended call is routine (the callee
4044
- * hangs up while AMD is still resolving), and handlers shouldn't have to
4045
- * guard against it.
6029
+ * If no assistant audio has been sent since the last barge-in this is a
6030
+ * no-op: there is nothing queued at Twilio to clear, no item id to name in a
6031
+ * truncate, and any response still generating is left to run.
6032
+ */
6033
+ private handleBargeIn;
6034
+ /**
6035
+ * Run a model-requested tool call and hand the result back.
4046
6036
  *
4047
- * @param callSid - Twilio Call SID (from a call event, the outbound result, or
4048
- * `ConversationSession.callSid`).
4049
- * @returns True if Twilio accepted the hangup, false if it failed (logged).
4050
- * Session cleanup runs either way.
6037
+ * Always sends a `function_call_output` once a `call_id` is present — even a
6038
+ * tool that ran successfully can return something `JSON.stringify` throws on
6039
+ * (a circular object, a `BigInt`) or has no JSON form at all, which
6040
+ * `JSON.stringify` reports by returning `undefined` rather than throwing (a
6041
+ * void tool, a bare function, a `Symbol`). Either way the model would
6042
+ * otherwise be left waiting on a `call_id` it never gets a result for.
6043
+ * Without a `call_id` there is nothing to reply to, so the item is dropped
6044
+ * instead.
4051
6045
  */
4052
- endCall(callSid: string): Promise<boolean>;
6046
+ private handleFunctionCall;
4053
6047
  /**
4054
- * Look up the active voice session for a Twilio Call SID.
6048
+ * Drop this call's transport state, close the model socket, and end the
6049
+ * session.
4055
6050
  *
4056
- * Out-of-band code holding a CallSid — a dashboard route, an operator action,
4057
- * a call-event handler — can't reach the session-facing methods, which are
4058
- * keyed by conversation id: the Orchestrator conversation id in orchestrator
4059
- * mode, the CallSid only in ConversationRelay-only mode.
6051
+ * Both legs can report the call ending, and the first one to arrive tears
6052
+ * down the other, so this runs at most once per call: a second invocation
6053
+ * finds nothing tracked and returns.
6054
+ */
6055
+ private cleanupCall;
6056
+ }
6057
+
6058
+ interface GPTLiveProviderConfigOptions extends MediaStreamsOpenAIProviderConfigOptions {
6059
+ /**
6060
+ * If set, sent verbatim as a `session.commentary.append` once `session.started`
6061
+ * arrives. Word it as an instruction, not just a greeting — e.g. "Greet the
6062
+ * caller immediately using: Hi, how can I help you today?". A bare greeting
6063
+ * will not make the model speak first.
6064
+ */
6065
+ welcomeInstruction?: string;
6066
+ }
6067
+ /**
6068
+ * Configuration for `GPTLiveProvider`.
6069
+ *
6070
+ * Two GPT-Live-specific notes on inherited members:
6071
+ *
6072
+ * - `tools` holds executable implementations looked up by name. It does **not**
6073
+ * tell the model the tools exist — also add each tool's `toRealtimeFormat()`
6074
+ * schema to `defaultSessionConfig.delegation.responses.tools`.
6075
+ * - `defaultSessionConfig` is the `session.start` payload's `session` body. It
6076
+ * must include `model` (e.g. `'gpt-live-1'`), and `audio.format`
6077
+ * must be `TWILIO_AUDIO_FORMAT_FOR_GPT_LIVE`.
6078
+ */
6079
+ declare class GPTLiveProviderConfig extends MediaStreamsOpenAIProviderConfig {
6080
+ readonly welcomeInstruction: string | null;
6081
+ constructor(opts?: GPTLiveProviderConfigOptions);
6082
+ createProvider(channel: VoiceChannel, tacConfig: TACConfig): VoiceProvider;
6083
+ }
6084
+
6085
+ /**
6086
+ * Per-call bookkeeping `GPTLiveProvider` needs beyond `ConversationSession`.
6087
+ *
6088
+ * @internal
6089
+ */
6090
+ declare class CallState extends MediaStreamsOpenAICallState {
6091
+ /**
6092
+ * Settles once `session.closed` arrives, so teardown can wait for graceful
6093
+ * finalization before tearing the socket down.
6094
+ */
6095
+ readonly closed: Promise<void>;
6096
+ private readonly resolveClosed;
6097
+ constructor();
6098
+ markClosed(): void;
6099
+ }
6100
+
6101
+ /**
6102
+ * The audio format both directions of a call must use.
6103
+ *
6104
+ * Twilio Media Streams always sends and expects 8kHz G.711 u-law — see
6105
+ * https://www.twilio.com/docs/voice/media-streams/websocket-messages. Not
6106
+ * configurable. GPT-Live speaks it natively on both legs, so a single
6107
+ * `session.audio.format` covers input and output and nothing transcodes.
6108
+ *
6109
+ * Spelled with an explicit `rate`, which GPT-Live's schema wants and Realtime's
6110
+ * rejects — that is why this is a separate constant from
6111
+ * `TWILIO_AUDIO_FORMAT_FOR_REALTIME` rather than a shared one.
6112
+ */
6113
+ declare const TWILIO_AUDIO_FORMAT_FOR_GPT_LIVE: {
6114
+ readonly type: "audio/pcmu";
6115
+ readonly rate: 8000;
6116
+ };
6117
+ /**
6118
+ * `ConversationSession.metadata` key holding OpenAI's id for the GPT-Live
6119
+ * session behind this call, set once `session.started` arrives. Quote it to
6120
+ * OpenAI support when reporting a session.
6121
+ *
6122
+ * Opaque: the prefix differs across GPT-Live's alpha (`rtc_`) and GA (`live_`),
6123
+ * so never parse it, validate it, or branch on it.
6124
+ */
6125
+ declare const GPT_LIVE_SESSION_ID_METADATA_KEY = "gpt_live_session_id";
6126
+ /**
6127
+ * A {@link VoiceProvider} bridging Twilio Media Streams to OpenAI's GPT-Live
6128
+ * API.
6129
+ */
6130
+ declare class GPTLiveProvider extends MediaStreamsOpenAIProvider<CallState> {
6131
+ /** @internal */
6132
+ get providerId(): string;
6133
+ /**
6134
+ * No `override`: TypeScript rejects it alongside `declare` (TS1243), and
6135
+ * `declare` is what keeps this a pure type narrowing of the base's field
6136
+ * rather than a second field that shadows it.
6137
+ */
6138
+ protected readonly config: GPTLiveProviderConfig;
6139
+ private readonly pendingTokenExpiries;
6140
+ /** Calls whose teardown has begun but is still awaiting `session.closed`. */
6141
+ private readonly closingCalls;
6142
+ get channelName(): string;
6143
+ /**
6144
+ * Initiate an outbound voice conversation.
4060
6145
  *
4061
- * Relay-only mode creates the session on the first prompt; orchestrated
4062
- * mode creates it when the lookup started at setup finishes, so it may
4063
- * exist before the caller speaks — including before `onAmd` fires. Treat it
4064
- * as racy and hang up with {@link endCall}, which needs no session.
6146
+ * Places an outbound call with inline TwiML that connects to a Media Stream.
6147
+ * Unlike inbound, there is no local session yet at this point — one is
6148
+ * created when Twilio's WebSocket `start` event arrives.
4065
6149
  *
4066
- * At the other end, orchestrator mode keeps the session until Conversation
4067
- * Orchestrator's CLOSED webhook, so it outlives the call and `onCallStatus` /
4068
- * `onRecording` do resolve. Relay-only mode tears down on the
4069
- * ConversationRelay callback instead, which races them.
6150
+ * TwiML fields are merged per-field — see
6151
+ * {@link TwiMLBuilderMediaStreams.build}. The WebSocket URL is derived from
6152
+ * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` unless
6153
+ * overridden per-call via `options.websocketUrl`.
4070
6154
  *
4071
- * @example
4072
- * ```typescript
4073
- * async function nudge(callSid: string): Promise<void> {
4074
- * const session = voiceChannel.getConversationSessionByCallSid(callSid);
4075
- * if (session) {
4076
- * await voiceChannel.sendResponse(session.conversationId, 'Still there?');
4077
- * }
4078
- * }
4079
- * ```
6155
+ * Pass `InitiateVoiceConversationOptionsGPTLive` with `sessionConfig` set to
6156
+ * override `GPTLiveProviderConfig.defaultSessionConfig` for this call.
4080
6157
  *
4081
- * @param callSid - Twilio Call SID, e.g. from
4082
- * `InitiateVoiceConversationResult.callSid` or a call event.
4083
- * @returns The session, or `undefined` — not created yet, the call ended, or
4084
- * it landed on another instance (see the horizontal-scaling note in
4085
- * CLAUDE.md).
6158
+ * @param options - Outbound call options.
6159
+ * @throws {TypeError} if `options` does not satisfy
6160
+ * `InitiateVoiceConversationOptionsGPTLiveSchema`.
6161
+ * @throws {Error} if no WebSocket URL can be resolved — neither
6162
+ * `options.websocketUrl` nor any TwiML layer sets one and
6163
+ * `TACConfig.voicePublicDomain` is unset.
4086
6164
  */
4087
- getConversationSessionByCallSid(callSid: string): ConversationSession | undefined;
6165
+ initiateOutboundConversation(options: InitiateVoiceConversationOptions | InitiateVoiceConversationOptionsGPTLive): Promise<InitiateVoiceConversationResult>;
4088
6166
  /**
4089
- * Start tracking a streaming task for a conversation
6167
+ * Start the clock on a stashed token, so a call that never connects cannot
6168
+ * strand its override in {@link pendingSessionConfigs} forever.
4090
6169
  *
4091
- * @param conversationId - The conversation ID
4092
- * @returns The stream task with its AbortController
6170
+ * Unref'd: a two-minute timer must not be what keeps the process alive after
6171
+ * the call it belongs to is long over.
4093
6172
  */
4094
- startStreamTask(conversationId: ConversationId): StreamTask;
6173
+ private armTokenExpiry;
4095
6174
  /**
4096
- * Cancel an active streaming task
6175
+ * Stop the clock on a token, once the call it belongs to has claimed it.
4097
6176
  *
4098
- * @param conversationId - The conversation ID
4099
- * @returns true if a task was cancelled, false otherwise
6177
+ * Without this a two-minute timer outlives every call that connected
6178
+ * normally, waiting to purge an entry that is already gone.
4100
6179
  */
4101
- cancelStreamTask(conversationId: ConversationId): boolean;
6180
+ private cancelTokenExpiry;
4102
6181
  /**
4103
- * Complete a streaming task (remove from tracking)
6182
+ * Drive one Twilio Media Stream connection from `start` to disconnect.
4104
6183
  *
4105
- * @param conversationId - The conversation ID
6184
+ * Twilio's `start` event names the call, which opens the matching GPT-Live
6185
+ * socket; from then on caller audio is relayed to the model and the model's
6186
+ * audio back to Twilio, until either side goes away. Whichever leg closes
6187
+ * first takes the other down with it, so a caller is never left connected to
6188
+ * silence.
6189
+ *
6190
+ * Twilio streams audio without waiting for the GPT-Live socket to finish
6191
+ * connecting, so audio that arrives during that handshake is held and
6192
+ * forwarded, in order, once the model is ready — a caller who speaks the
6193
+ * instant the call connects is heard in full.
6194
+ *
6195
+ * Called by `VoiceChannel.handleWebSocketConnection`; hosts serve the socket
6196
+ * rather than calling this directly.
6197
+ *
6198
+ * @param ws - The accepted Twilio-facing WebSocket.
4106
6199
  */
4107
- completeStreamTask(conversationId: ConversationId): void;
6200
+ handleWebSocket(ws: WebSocket): void;
4108
6201
  /**
4109
- * Check if a stream task is active
6202
+ * Handle Twilio's `start` event: track the call and open its session.
4110
6203
  *
4111
- * @param conversationId - The conversation ID
4112
- * @returns true if an active task exists
6204
+ * @param start - The event's `start` body, parsed against
6205
+ * `StreamStartMessageSchema`.
6206
+ * @param ws - The Twilio-facing socket this call arrived on.
6207
+ * @returns The conversation id — which is the call SID — and the call's
6208
+ * freshly tracked transport state.
4113
6209
  */
4114
- hasActiveStreamTask(conversationId: ConversationId): boolean;
6210
+ private registerCall;
4115
6211
  /**
4116
- * Field names on {@link TwiMLOptions} that map directly to `<ConversationRelay>`
4117
- * attributes (camelCase, emitted as-is). Excludes the fields handled specially
4118
- * by {@link generateTwiml}: websocketUrl (resolved through the layered merge and
4119
- * emitted as the `url` attribute), actionUrl, languages, customParameters, extra.
6212
+ * Open this call's GPT-Live socket and send its session config.
6213
+ *
6214
+ * @internal
4120
6215
  */
4121
- private static readonly RELAY_ATTR_FIELDS;
6216
+ connectModel(conversationId: ConversationId): Promise<void>;
4122
6217
  /**
4123
- * Generate TwiML XML for ConversationRelay from a merged {@link TwiMLOptions}.
4124
- *
4125
- * This is the low-level emitter used by `handleIncomingCall` and
4126
- * `initiateOutboundConversation` after layering. It mirrors the Python SDK's
4127
- * `generate_twiml`. The WebSocket URL may be passed as `websocketUrl` or via
4128
- * `options.websocketUrl` (the explicit argument wins when both are given), so a
4129
- * channel-less caller can pass everything in one object.
6218
+ * The validated session config for this call: its own stashed override if it
6219
+ * has one, else the channel-wide default.
4130
6220
  *
4131
- * @param websocketUrl - Public WebSocket URL (e.g. 'wss://example.ngrok.app/ws').
4132
- * Optional if `options.websocketUrl` is set.
4133
- * @param options - Merged TwiMLOptions to emit.
4134
- * @returns TwiML XML string ready to return to Twilio.
4135
- * @throws {Error} if no WebSocket URL is provided via either source.
6221
+ * @throws {Error} if neither exists, if the audio format is one Twilio can't
6222
+ * carry, or if it names no model.
4136
6223
  */
4137
- private generateTwiml;
6224
+ private resolveSessionConfig;
4138
6225
  /**
4139
- * Generate TwiML to connect a call to ConversationRelay.
4140
- * Validates configuration with Zod before generating TwiML.
6226
+ * Wire up the model socket: dispatch its events, and tear the call down when
6227
+ * it goes away.
4141
6228
  *
4142
- * @param config - ConversationRelay configuration (url, transcription, TTS, etc.)
4143
- * @param options - Optional settings for parameters and the Connect verb
4144
- * @returns TwiML XML string
4145
- * @throws {Error} if config validation fails
6229
+ * The Python SDK races its Twilio read against its model-event reader so the
6230
+ * Twilio leg dies with the model leg; `ws` is event-driven, so the same
6231
+ * guarantee is a close/error handler instead.
6232
+ */
6233
+ private attachModelHandlers;
6234
+ /**
6235
+ * Hang up the Twilio leg because the model leg is gone, then clean up. A
6236
+ * no-op once the call has already been cleaned up, so both the model socket's
6237
+ * `close` and its `error` can call it.
4146
6238
  */
4147
- connectConversationRelay(config: ConversationRelayConfig, options?: {
4148
- parameters?: CustomParameters;
4149
- actionUrl?: string;
4150
- }): string;
6239
+ private endCallFromModel;
4151
6240
  /**
4152
- * Filter out undefined values from configuration object.
4153
- * Keeps null, false, 0, and empty strings as they are valid values.
6241
+ * Close this call's GPT-Live session gracefully, drop its transport state,
6242
+ * and end the session.
6243
+ *
6244
+ * `session.close` asks the server to finalize the session, and teardown waits
6245
+ * up to {@link CLOSE_TIMEOUT_MS} for the `session.closed` answering it before
6246
+ * the socket goes away — otherwise the socket would be gone before the server
6247
+ * could finish.
6248
+ *
6249
+ * Both legs can report the call ending, and the first one to arrive tears
6250
+ * down the other, so this runs at most once per call: a second invocation
6251
+ * finds the call either untracked or already closing, and returns.
4154
6252
  */
4155
- private filterUnsetValues;
6253
+ private cleanupCall;
4156
6254
  /**
4157
- * Cleanup channel state on shutdown
6255
+ * Drop this provider's transport state on channel shutdown, including the
6256
+ * bookkeeping it keeps beyond the base class's.
4158
6257
  *
4159
- * Note: WebSocket connections are managed by the server and closed there.
4160
- * This method only cleans up internal channel state.
6258
+ * The token expiry timers are unref'd and delete themselves, so nothing hangs
6259
+ * without this — but a shut-down provider must not still be holding entries
6260
+ * for calls that can no longer arrive.
4161
6261
  */
4162
6262
  shutdown(): void;
6263
+ /** Apply one parsed GPT-Live event to the call. */
6264
+ protected dispatchModelEvent(conversationId: ConversationId, session: ConversationSession, event: Record<string, unknown>): Promise<void>;
6265
+ /**
6266
+ * Run a Responses-delegated tool call and hand the result back.
6267
+ *
6268
+ * Always sends a `function_call_output` once a `call_id` is present — even a
6269
+ * tool that ran successfully can return something `JSON.stringify` throws on
6270
+ * (a circular object, a `BigInt`) or has no JSON form at all, which
6271
+ * `JSON.stringify` reports by returning `undefined` rather than throwing (a
6272
+ * void tool, a bare function, a `Symbol`). Either way the model would
6273
+ * otherwise be left waiting on a `call_id` it never gets a result for.
6274
+ * Without a `call_id` there is nothing to reply to, so the item is dropped
6275
+ * instead.
6276
+ */
6277
+ private handleFunctionCall;
6278
+ /**
6279
+ * Surface the GPT-Live session id from a session-snapshot event.
6280
+ *
6281
+ * OpenAI support asks for this id when investigating a session, so it goes
6282
+ * where a caller can reach it — `session.metadata`, which outlives the call
6283
+ * into `onConversationEnded` — and is logged once per call.
6284
+ */
6285
+ private recordGptLiveSessionId;
6286
+ /** Accumulate one transcript delta into the in-progress turn. */
6287
+ private static appendTranscriptDelta;
4163
6288
  }
4164
6289
 
4165
6290
  declare function scrubPii(value: string): string;
@@ -4354,243 +6479,6 @@ declare class MemoryPromptBuilder {
4354
6479
  private static assemblePrompt;
4355
6480
  }
4356
6481
 
4357
- /**
4358
- * TAC Tool class with helper methods for LLM integration
4359
- *
4360
- * Matches Python's TACTool dataclass with conversion methods.
4361
- */
4362
- declare class TACTool<TParams = unknown, TResult = unknown> {
4363
- readonly name: string;
4364
- readonly description: string;
4365
- readonly parameters: JSONSchema;
4366
- readonly implementation: ToolFunction<TParams, TResult>;
4367
- constructor(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>);
4368
- /**
4369
- * Convert to OpenAI function calling format
4370
- */
4371
- toOpenAIFormat(): OpenAITool;
4372
- /**
4373
- * Convert to Anthropic tool calling format
4374
- */
4375
- toAnthropicFormat(): AnthropicTool;
4376
- /**
4377
- * Convert to JSON string (OpenAI format by default)
4378
- */
4379
- toJSON(): string;
4380
- /**
4381
- * Convert this tool to an OpenAI Agents SDK `FunctionTool` instance.
4382
- *
4383
- * Unlike `toOpenAIFormat` and `toAnthropicFormat` (which return plain
4384
- * objects consumed by HTTP APIs), the OpenAI Agents SDK dispatches on tool
4385
- * *type*, so this returns a live `tool(...)` object with an invoke callback
4386
- * that calls this tool and JSON-encodes the result.
4387
- *
4388
- * Requires the `@openai/agents` package:
4389
- *
4390
- * npm install @openai/agents
4391
- *
4392
- * @returns A FunctionTool ready to pass to `new Agent({ tools: [...] })`.
4393
- */
4394
- toOpenAIAgentsSDKTool(): Promise<any>;
4395
- }
4396
- /**
4397
- * Create a tool directly with all parameters
4398
- *
4399
- * Simplified approach matching Python's create_tool function.
4400
- * No builder pattern - just a simple function call.
4401
- */
4402
- declare function defineTool<TParams = unknown, TResult = unknown>(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>): TACTool<TParams, TResult>;
4403
-
4404
- /**
4405
- * Parameters for memory retrieval tool
4406
- */
4407
- interface MemoryRetrievalParams {
4408
- query?: string;
4409
- beginDate?: string;
4410
- endDate?: string;
4411
- observationsLimit?: number;
4412
- summariesLimit?: number;
4413
- communicationsLimit?: number;
4414
- relevanceThreshold?: number;
4415
- }
4416
- /**
4417
- * Create memory retrieval tool.
4418
- *
4419
- * @param memoryClient - Memory client instance (must be initialized with storeId)
4420
- * @param profileId - Optional profile ID for memory retrieval
4421
- * @param conversationId - Optional conversation ID for memory retrieval
4422
- * @param options - Optional overrides for tool metadata.
4423
- * @param options.name - Tool name exposed to the LLM. Defaults to `retrieve_profile_memory`.
4424
- * @param options.description - Tool description exposed to the LLM. Defaults to a
4425
- * generic "retrieve memories" prompt.
4426
- */
4427
- declare function createMemoryRetrievalTool(memoryClient: MemoryClient, profileId?: string, conversationId?: string, options?: {
4428
- name?: string;
4429
- description?: string;
4430
- }): TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
4431
- /**
4432
- * Create factory function for memory tools
4433
- *
4434
- * @param memoryClient - Memory client instance (must be initialized with storeId)
4435
- */
4436
- declare function createMemoryTools(memoryClient: MemoryClient): {
4437
- forProfile: (profileId: string, conversationId?: string) => TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
4438
- forSession: (profileId?: string, conversationId?: string) => TACTool<MemoryRetrievalParams, MemoryRetrievalResponse>;
4439
- };
4440
-
4441
- /**
4442
- * Parameters for send message tool
4443
- */
4444
- interface SendMessageParams {
4445
- message: string;
4446
- metadata?: Record<string, unknown>;
4447
- }
4448
- /**
4449
- * Result from send message tool
4450
- */
4451
- interface SendMessageResult {
4452
- success: boolean;
4453
- message_id?: string;
4454
- error?: string;
4455
- }
4456
- /**
4457
- * Create send message tool
4458
- */
4459
- declare function createSendMessageTool(channel: BaseChannel, conversationId: ConversationId): TACTool<SendMessageParams, SendMessageResult>;
4460
- /**
4461
- * Create factory function for messaging tools
4462
- */
4463
- declare function createMessagingTools(): {
4464
- forConversation: (channel: BaseChannel, conversationId: ConversationId) => TACTool<SendMessageParams, SendMessageResult>;
4465
- };
4466
-
4467
- /**
4468
- * Handoff tool for the Twilio Agent Connect.
4469
- *
4470
- * Generic Studio-backed handoff that routes a conversation to a human agent.
4471
- * Produces a structured HandoffPayload and delivers it as a Twilio Studio
4472
- * Execution (voice via `<Connect action>`, digital channels via direct POST).
4473
- */
4474
-
4475
- /**
4476
- * Build a HandoffPayload from session context and attributes.
4477
- *
4478
- * Useful for custom handoff tools that want TAC's payload shape without
4479
- * the Studio-specific delivery in `postStudioHandoff`.
4480
- */
4481
- declare function buildHandoffPayload(session: ConversationSession, memoryStoreId: string, attributes: Record<string, unknown>): HandoffPayload;
4482
- /**
4483
- * POST a handoff payload to a Twilio Studio Flow Executions endpoint.
4484
- *
4485
- * Emits the Twilio Studio Executions API wire format: form-encoded
4486
- * `To` / `From` / `Parameters` fields with HTTP Basic auth.
4487
- * `Parameters` is a JSON string keyed under `HandoffData` so Studio
4488
- * can reference it via `{{flow.data.HandoffData.*}}`.
4489
- */
4490
- declare function postStudioHandoff(payload: HandoffPayload, session: ConversationSession, options: {
4491
- handoffUrl: string;
4492
- fromAddress: string;
4493
- apiKey: string;
4494
- apiSecret: string;
4495
- }): Promise<void>;
4496
- /**
4497
- * Result returned by the handoff tool.
4498
- */
4499
- interface HandoffResult {
4500
- status: 'handoff_initiated' | 'handoff_failed';
4501
- channel: string;
4502
- error?: string;
4503
- }
4504
- interface HandoffParams {
4505
- reason: string;
4506
- }
4507
- /**
4508
- * Create a handoff tool that delivers in the Twilio Studio Executions API shape.
4509
- *
4510
- * The returned tool exposes only `handoff({ reason })` to the LLM. All other
4511
- * dependencies (TAC instance, session, static attributes) are captured in the
4512
- * closure.
4513
- *
4514
- * On digital channels, the tool POSTs to the Studio Flow Executions endpoint
4515
- * derived from `tac.getConfig().studioHandoffFlowSid`. For voice channels,
4516
- * the payload is stored on the session and the voice channel automatically
4517
- * sends the WS `end` message with `handoffData` after the LLM's final
4518
- * response is delivered.
4519
- *
4520
- * The tool also sets the conversation to INACTIVE and clears status callbacks
4521
- * to prevent further webhook events from being routed to TAC.
4522
- *
4523
- * **Not available in voice-only mode.** This tool requires Conversation
4524
- * Orchestrator for conversation state management and Conversation Memory for
4525
- * the handoff payload. In voice-only mode, implement your own handoff by
4526
- * setting `session.pendingHandoffData` directly — the voice channel will
4527
- * send the WS `end` message with your payload, and your `<Connect action>`
4528
- * URL handler can route the call accordingly.
4529
- *
4530
- * @throws Error if `tac.getConfig().studioHandoffFlowSid` is unset, if
4531
- * Conversation Orchestrator is not configured (voice-only mode), or if
4532
- * the memory store ID was not resolved at startup.
4533
- */
4534
- declare function createStudioHandoffTool(tac: TAC, session: ConversationSession, options?: {
4535
- attributes?: Record<string, unknown>;
4536
- name?: string;
4537
- description?: string;
4538
- }): TACTool<HandoffParams, HandoffResult>;
4539
-
4540
- /**
4541
- * Parameters for knowledge search tool (visible to LLM)
4542
- */
4543
- interface KnowledgeSearchParams {
4544
- query: string;
4545
- }
4546
- /**
4547
- * Configuration for knowledge search tool
4548
- */
4549
- interface KnowledgeToolConfig {
4550
- name?: string;
4551
- description?: string;
4552
- topK?: number;
4553
- }
4554
- /**
4555
- * Create knowledge search tool with explicit name and description
4556
- *
4557
- * @param knowledgeClient - The Knowledge client instance
4558
- * @param knowledgeBaseId - The knowledge base ID to search
4559
- * @param config - Configuration with required name and description
4560
- * @returns TACTool configured for knowledge search
4561
- */
4562
- declare function createKnowledgeSearchTool(knowledgeClient: KnowledgeClient, knowledgeBaseId: string, config: {
4563
- name: string;
4564
- description: string;
4565
- topK?: number;
4566
- }): TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>;
4567
- /**
4568
- * Create knowledge search tool with auto-fetched metadata from knowledge base
4569
- *
4570
- * This async version fetches the knowledge base metadata to auto-generate
4571
- * the tool name and description if not provided.
4572
- *
4573
- * @param knowledgeClient - The Knowledge client instance
4574
- * @param knowledgeBaseId - The knowledge base ID to search
4575
- * @param config - Optional configuration (name/description auto-generated if not provided)
4576
- * @returns Promise containing TACTool configured for knowledge search
4577
- */
4578
- declare function createKnowledgeSearchToolAsync(knowledgeClient: KnowledgeClient, knowledgeBaseId: string, config?: KnowledgeToolConfig): Promise<TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>>;
4579
- /**
4580
- * Create factory for knowledge tools
4581
- *
4582
- * @param knowledgeClient - The Knowledge client instance
4583
- * @returns Factory object with methods to create knowledge tools
4584
- */
4585
- declare function createKnowledgeTools(knowledgeClient: KnowledgeClient): {
4586
- forKnowledgeBase: (knowledgeBaseId: string, config: {
4587
- name: string;
4588
- description: string;
4589
- topK?: number;
4590
- }) => TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>;
4591
- forKnowledgeBaseAsync: (knowledgeBaseId: string, config?: KnowledgeToolConfig) => Promise<TACTool<KnowledgeSearchParams, KnowledgeChunkResult[]>>;
4592
- };
4593
-
4594
6482
  /**
4595
6483
  * Server configuration options
4596
6484
  */
@@ -4627,9 +6515,18 @@ interface TACServerConfig {
4627
6515
  /** Path for Conversation Intelligence webhook (optional - only registered if provided) */
4628
6516
  cintel?: string;
4629
6517
  };
4630
- /** Voice channel instance (alternative to registering on TAC) */
6518
+ /**
6519
+ * Voice channel to serve. The server registers it on TAC (see
6520
+ * {@link TAC.registerChannel}), so it doesn't need registering separately.
6521
+ * Defaults to the voice channel already registered on TAC, if any.
6522
+ */
4631
6523
  voiceChannel?: VoiceChannel;
4632
- /** Messaging channel instances — webhooks are fanned out to all (alternative to registering on TAC) */
6524
+ /**
6525
+ * Messaging channels to serve; conversation webhooks are fanned out to all of
6526
+ * them. The server registers each on TAC (see {@link TAC.registerChannel}), so
6527
+ * they don't need registering separately. Defaults to the SMS, RCS, Chat and
6528
+ * WhatsApp channels already registered on TAC.
6529
+ */
4633
6530
  messagingChannels?: MessagingChannel[];
4634
6531
  }
4635
6532
  /**
@@ -4712,4 +6609,4 @@ declare class TACServer {
4712
6609
  stop(): Promise<void>;
4713
6610
  }
4714
6611
 
4715
- export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AmdEvent, AmdEventSchema, type AmdHandler, type AnthropicTool, AnthropicToolSchema, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, CALL_EVENT_KINDS, type CallEventKind, CallEventKindSchema, type CallOptions, CallOptionsSchema, type CallStatusEvent, CallStatusEventSchema, type CallStatusHandler, type CaptureRule, CaptureRuleSchema, type ChannelSettings, ChannelSettingsSchema, type ChannelType, ChannelTypeSchema, ChatChannel, type ChatChannelConfig, type CintelParticipant, CintelParticipantSchema, type Communication, type CommunicationContent, CommunicationContentSchema, type CommunicationParticipant, CommunicationParticipantSchema, CommunicationSchema, type ConversationAddress, ConversationAddressSchema, ConversationClient, type ConversationConfiguration, ConversationConfigurationSchema, type ConversationEndedCallback, type ConversationGroupingType, ConversationGroupingTypeSchema, type ConversationId, type ConversationIntelligenceConfig, ConversationIntelligenceConfigSchema, type ConversationParticipant, ConversationParticipantSchema, type ConversationRelayAttributes, ConversationRelayAttributesSchema, type ConversationRelayCallbackPayload, ConversationRelayCallbackPayloadSchema, type ConversationRelayConfig, ConversationRelayConfigSchema, type ConversationResponse, ConversationResponseSchema, type ConversationSession, ConversationSessionSchema, type ConversationSummaryItem, ConversationSummaryItemSchema, type ConversationWebhookPayload, type CreateConversationSummariesResponse, CreateConversationSummariesResponseSchema, type CreateObservationResponse, CreateObservationResponseSchema, type CreateObservationsRequest, CreateObservationsRequestSchema, type CustomParameters, CustomParametersSchema, type DtmfEvent, type DtmfHandler, type DtmfMessage, DtmfMessageSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type InterruptMode, InterruptModeSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, type LanguageConfig, LanguageConfigSchema, type ListCommunicationsResponse, ListCommunicationsResponseSchema, type ListConversationsResponse, ListConversationsResponseSchema, type ListParticipantsResponse, ListParticipantsResponseSchema, type Logger, type MemoryChannelType, MemoryChannelTypeSchema, MemoryClient, type MemoryCommunication, type MemoryCommunicationContent, MemoryCommunicationContentSchema, MemoryCommunicationSchema, type MemoryDeliveryStatus, MemoryDeliveryStatusSchema, type MemoryMode, MemoryModeSchema, type MemoryParticipant, MemoryParticipantSchema, type MemoryParticipantType, MemoryParticipantTypeSchema, MemoryPromptBuilder, type MemoryRetrievalRequest, MemoryRetrievalRequestSchema, type MemoryRetrievalResponse, MemoryRetrievalResponseSchema, type MessageDirection, MessageDirectionSchema, type MessageReadyCallback, MessagingChannel, type MessagingChannelConfig, type MessagingChannelEvents, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, type OpenAITool, OpenAIToolSchema, type Operator, type OperatorProcessingResult, OperatorProcessingResultSchema, type OperatorResult, type OperatorResultEvent, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, type ParticipantAddress, ParticipantAddressSchema, type ParticipantAddressType, ParticipantAddressTypeSchema, type ParticipantId, type PendingHandoffData, PendingHandoffDataSchema, type Profile, type ProfileId, type ProfileLookupResponse, ProfileLookupResponseSchema, type ProfileResponse, ProfileResponseSchema, type PromptMessage, PromptMessageSchema, RCSChannel, type RecordingEvent, RecordingEventSchema, type RecordingHandler, SMSChannel, type SendMessageActionPayload, SendMessageActionPayloadSchema, type SendMessageActionRequest, SendMessageActionRequestSchema, type SessionInfo, SessionInfoSchema, type SessionMessage, SessionMessageSchema, type SetupMessage, SetupMessageSchema, type StatusCallback, StatusCallbackSchema, type StatusTimeouts, StatusTimeoutsSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
6612
+ 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, 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, 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 };