Skip to main content

Class: TwilioVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:184

Twilio voice call provider.

Uses the Twilio REST API 2010-04-01 for outbound call control and HMAC-SHA1 for inbound webhook signature verification.

Example​

const provider = new TwilioVoiceProvider({
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken:  process.env.TWILIO_AUTH_TOKEN!,
});

Implements​

Constructors​

Constructor​

new TwilioVoiceProvider(config): TwilioVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:203

Parameters​

config​

TwilioVoiceProviderConfig

Twilio credentials and optional overrides.

Returns​

TwilioVoiceProvider

Properties​

name​

readonly name: "twilio"

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:186

Provider identifier, always 'twilio'.

Implementation of​

IVoiceCallProvider.name

Methods​

hangupCall()​

hangupCall(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:404

Hang up an active call by POSTing Status=completed.

Twilio uses the same Calls resource endpoint for both querying and modifying a call. Setting Status=completed instructs Twilio to immediately terminate the call.

Parameters​

input​

HangupCallInput

Contains the Twilio CallSid to hang up.

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.hangupCall

initiateCall()​

initiateCall(input): Promise<InitiateCallResult>

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:362

Initiate an outbound call via the Twilio Calls API.

Posts to /Accounts/{accountSid}/Calls.json with a form-encoded body (not JSON -- this is Twilio's 2010-era API convention). All four status callback events (initiated, ringing, answered, completed) are requested so the CallManager receives the full state progression.

Parameters​

input​

InitiateCallInput

Call initiation parameters (from/to numbers, webhook URLs).

Returns​

Promise<InitiateCallResult>

Result containing the Twilio CallSid on success.

Throws​

Never throws; returns { success: false, error: '...' } on failure.

Implementation of​

IVoiceCallProvider.initiateCall

parseWebhookEvent()​

parseWebhookEvent(ctx): WebhookParseResult

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:288

Parse a Twilio webhook body into normalized NormalizedCallEvents.

Twilio sends webhooks with a form-encoded body containing CallSid, CallStatus, and optionally Digits (for DTMF input from <Gather>). Each webhook may produce one or two events (status + optional DTMF).

Parameters​

ctx​

WebhookContext

Raw webhook request context.

Returns​

WebhookParseResult

Parsed result containing zero or more normalized events.

Implementation of​

IVoiceCallProvider.parseWebhookEvent

playTts()​

playTts(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:429

Inject TTS into a live call using a TwiML <Say> verb.

Sends a Twiml form parameter containing a minimal <Response><Say> document. Twilio will parse the TwiML, synthesise the speech, and play it to the caller in real-time.

The optional voice attribute maps to Twilio's built-in voice names (e.g., alice, Polly.Joanna).

Parameters​

input​

PlayTtsInput

TTS parameters (text, voice, call ID).

Returns​

Promise<void>

Implementation of​

IVoiceCallProvider.playTts

verifyWebhook()​

verifyWebhook(ctx): WebhookVerificationResult

Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:237

Verify an incoming Twilio webhook request using HMAC-SHA1.

Algorithm (step by step)​

  1. Extract the X-Twilio-Signature header from the request.
  2. Parse the request body as URL-encoded form data.
  3. Sort the keys in case-sensitive code-unit order, as twilio-node's getExpectedTwilioSignature does. A locale-aware sort puts Called before CallSid and fails every real voice webhook.
  4. Build the signed string: start with the full URL, then append each key + value (no delimiters between pairs). A repeated key contributes each distinct value, sorted, so a webhook whose CallSid, CallStatus or Digits repeats with different values is refused.
  5. Compute HMAC-SHA1 of the signed string using the auth token as the key.
  6. Base64-encode the digest and compare it to the header value.
  7. Repeat with the URL with and without its port, as twilio-node does (see twilioUrlVariants); any match is valid.

Parameters​

ctx​

WebhookContext

Raw webhook request context.

Returns​

WebhookVerificationResult

Verification result with valid: true if the signature matches.

Implementation of​

IVoiceCallProvider.verifyWebhook