import type { SessionAuthContext } from "#channel/types.js"; import type { SessionContext } from "#public/definitions/callback-context.js"; import type { ChannelSessionOps } from "#public/definitions/defineChannel.js"; import type { HandleMessageStreamEvent } from "#protocol/message.js"; import { type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials } from "#public/channels/twilio/api.js"; import { type TwilioTextMessage, type TwilioVoiceCall, type TwilioVoiceTranscription } from "#public/channels/twilio/inbound.js"; import { type TwilioAuthToken, type TwilioWebhookUrl } from "#public/channels/twilio/verify.js"; import { type Channel } from "#public/definitions/defineChannel.js"; type EventData = Extract extends { data: infer D; } ? D : undefined; /** Pre-dispatch Twilio context passed to the inbound text, voice, and voice-transcription hooks. */ export interface TwilioContext { readonly twilio: TwilioHandle; } /** Channel-owned Twilio context returned by `context()`. */ export interface TwilioChannelContext extends TwilioContext { state: TwilioChannelState; } /** Event-handler Twilio context, including session operations. */ export interface TwilioEventContext extends TwilioChannelContext, ChannelSessionOps { } /** JSON-serializable state for the phone-number conversation. */ export interface TwilioChannelState { /** Caller / sender phone number. */ from: string | null; /** Twilio number or sender that received the latest session-starting webhook. */ to: string | null; /** Most recent inbound SMS SID when this session was started by text. */ lastMessageSid?: string | null; /** Most recent inbound Call SID when this session was started by voice. */ lastCallSid?: string | null; } /** Per-session instrumentation snapshot for Twilio runtime telemetry. Reports the active phone-number pair and the most recent message and call SIDs. */ export interface TwilioInstrumentationMetadata extends Record { readonly from: string | null; readonly lastCallSid: string | null; readonly lastMessageSid: string | null; readonly to: string | null; } /** Twilio channel credentials. `authToken` also verifies inbound webhook signatures. */ export interface TwilioChannelCredentials extends TwilioCredentials { readonly authToken?: TwilioAuthToken; } /** Target accepted by `receive(twilio, { target })` for proactive phone-number sessions. */ export interface TwilioReceiveTarget { readonly phoneNumber: string; /** Twilio sender included in the phone-pair continuation token. */ readonly from?: string; } /** Result of an inbound Twilio text or transcription hook. Return `null` (or `undefined`) to drop the webhook without dispatching; otherwise supply the session `auth` context. */ export type TwilioInboundResult = { auth: SessionAuthContext | null; } | null; /** Sync or async {@link TwilioInboundResult}. */ export type TwilioInboundResultOrPromise = TwilioInboundResult | Promise; /** Phone-number allow list for inbound Twilio webhook triggers. `"*"` allows every sender. */ export type TwilioAllowFrom = string | readonly string[] | (() => string | readonly string[] | Promise); /** * Result of an inbound Twilio voice hook. Return `null` to reject the call. * Any result other than `null` accepts the call and can override the answering TwiML. */ export interface TwilioVoiceResult { /** Prompt spoken before Twilio starts speech recognition. */ readonly prompt?: string; /** BCP 47 language used for speech recognition and the nested `` prompt. */ readonly language?: string; /** Twilio `` used for the prompt, e.g. `Polly.Joanna-Neural`. */ readonly voice?: string; /** Twilio `` used for speech recognition. */ readonly speechModel?: string; /** Twilio `` in seconds. */ readonly timeoutSeconds?: number; /** Twilio ``, such as `"auto"` or a second count string. */ readonly speechTimeout?: string; /** Twilio `` for expected words or phrases. */ readonly hints?: string | readonly string[]; /** Twilio `` toggle. */ readonly profanityFilter?: boolean; } /** Sync or async {@link TwilioVoiceResult}. */ export type TwilioVoiceResultOrPromise = TwilioVoiceResult | null | undefined | Promise; type TwilioEventHandler = (data: EventData, channel: TwilioEventContext, ctx: SessionContext) => void | Promise; type TwilioSessionFailedHandler = (data: EventData<"session.failed">, channel: TwilioEventContext) => void | Promise; /** Event handlers supported by `twilioChannel({ events })`. */ export interface TwilioChannelEvents { readonly "turn.started"?: TwilioEventHandler<"turn.started">; readonly "actions.requested"?: TwilioEventHandler<"actions.requested">; readonly "action.result"?: TwilioEventHandler<"action.result">; readonly "message.completed"?: TwilioEventHandler<"message.completed">; readonly "message.appended"?: TwilioEventHandler<"message.appended">; readonly "input.requested"?: TwilioEventHandler<"input.requested">; readonly "turn.failed"?: TwilioEventHandler<"turn.failed">; readonly "turn.completed"?: TwilioEventHandler<"turn.completed">; readonly "session.failed"?: TwilioSessionFailedHandler; readonly "session.completed"?: TwilioEventHandler<"session.completed">; readonly "session.waiting"?: TwilioEventHandler<"session.waiting">; readonly "authorization.required"?: TwilioEventHandler<"authorization.required">; readonly "authorization.completed"?: TwilioEventHandler<"authorization.completed">; } /** SMS/Messaging defaults for Twilio outbound replies. */ export interface TwilioMessagingConfig { /** Sender phone number. Defaults to the inbound `To` number when available. */ readonly from?: string; /** Messaging Service SID. Used instead of `from` when supplied. */ readonly messagingServiceSid?: string; /** Optional Twilio status callback URL for outbound messages. */ readonly statusCallbackUrl?: string; } /** Voice webhook defaults for accepting calls and gathering speech. */ export interface TwilioVoiceConfig { /** Prompt spoken when a caller reaches the voice route. */ readonly prompt?: string; /** Twilio `` used for the prompt, e.g. `Polly.Joanna-Neural`. */ readonly voice?: string; /** Spoken acknowledgement after a transcription webhook is accepted. */ readonly acknowledgement?: string; /** BCP 47 language used for speech recognition and the nested `` prompt. */ readonly language?: string; /** Twilio `` used for speech recognition. */ readonly speechModel?: string; /** Twilio `` in seconds. */ readonly timeoutSeconds?: number; /** Twilio ``, such as `"auto"` or a second count string. */ readonly speechTimeout?: string; /** Twilio `` for expected words or phrases. */ readonly hints?: string | readonly string[]; /** Twilio `` toggle. */ readonly profanityFilter?: boolean; } /** Configuration for {@link twilioChannel}. */ export interface TwilioChannelConfig { readonly credentials?: TwilioChannelCredentials; /** * Base route for Twilio webhooks. Defaults to `/eve/v1/twilio` and * mounts `/messages`, `/voice`, and `/voice/transcription` below it. */ readonly route?: string; /** * Public URL Twilio used for signing. Set this when proxies or local * tunnels make `request.url` differ from the configured webhook URL. */ readonly webhookUrl?: TwilioWebhookUrl; /** Public base URL used to render absolute voice `` URLs. */ readonly publicBaseUrl?: string | ((request: Request) => string | Promise); /** * Exact caller/sender numbers allowed to reach inbound hooks, or `"*"` to * allow every verified Twilio sender. Resolvers run on each inbound webhook. */ readonly allowFrom: TwilioAllowFrom; readonly messaging?: TwilioMessagingConfig; readonly voice?: TwilioVoiceConfig; readonly api?: Omit; /** Inbound text hook. Defaults to phone-number auth and dispatch. */ onText?(ctx: TwilioContext, message: TwilioTextMessage): TwilioInboundResultOrPromise; /** Inbound voice hook. Return `null` to reject the call before gathering speech. */ onVoice?(ctx: TwilioContext, call: TwilioVoiceCall): TwilioVoiceResultOrPromise; /** Inbound voice transcription hook. Defaults to phone-number auth and dispatch. */ onVoiceTranscription?(ctx: TwilioContext, transcription: TwilioVoiceTranscription): TwilioInboundResultOrPromise; readonly events?: TwilioChannelEvents; } /** Low-level Twilio handle exposed to hooks and event handlers. */ export interface TwilioHandle { /** Caller / sender phone number bound to this conversation. */ readonly from: string; /** Twilio receiver / sender number for replies, when known. */ readonly to: string | undefined; /** Most recent call SID, when the session started from a voice transcription. */ readonly callSid: string | undefined; /** Raw Twilio REST API escape hatch. `path` is appended to the API base URL (default `https://api.twilio.com`). `body` fields are POSTed as form-encoded parameters. */ request(path: string, body: Readonly>): Promise; /** Sends a text message to this conversation's phone number by default. */ sendMessage(message: string, options?: TwilioSendMessageOptions): Promise; /** Updates a live call with replacement TwiML. */ updateCall(callSid: string, twiml: string): Promise; } /** Per-call overrides for {@link TwilioHandle.sendMessage}. */ export interface TwilioSendMessageOptions { /** Recipient phone number. Defaults to the conversation's `from` number. */ readonly to?: string; /** Sender phone number. Defaults to `messaging.from`, falling back to the inbound `To` number. */ readonly from?: string; /** Messaging Service SID. Defaults to `messaging.messagingServiceSid`. */ readonly messagingServiceSid?: string; /** Twilio status callback URL. Defaults to `messaging.statusCallbackUrl`. */ readonly statusCallbackUrl?: string; } /** Concrete return type of {@link twilioChannel}. */ export interface TwilioChannel extends Channel { } /** Twilio channel factory for SMS and speech-transcribed inbound calls. */ export declare function twilioChannel(config: TwilioChannelConfig): TwilioChannel; export {};