Class: TwilioVoiceProvider
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:191
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:213
Parameters
config
TwilioVoiceProviderConfig
Twilio credentials and optional overrides.
Returns
TwilioVoiceProvider
Properties
name
readonlyname:"twilio"
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:193
Provider identifier, always 'twilio'.
Implementation of
Accessors
webhookIdentity
Get Signature
get webhookIdentity():
"legacy"|"stable-v1"
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:196
Declares whether callback ids satisfy the durable manager contract.
Returns
"legacy" | "stable-v1"
Stable normalized identity contract required by durable callback processing.
Implementation of
IVoiceCallProvider.webhookIdentity
Methods
hangupCall()
hangupCall(
input):Promise<void>
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:425
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
Contains the Twilio CallSid to hang up.
Returns
Promise<void>
Implementation of
initiateCall()
initiateCall(
input):Promise<InitiateCallResult>
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:383
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
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:305
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).
In carrier mode a request other than POST yields no events (Twilio signs
a GET by its URL alone, so a body there carries nothing Twilio signed),
and each event carries a stable id from stableCarrierEvents: a
DTMF event's occurrence is the signed SequenceNumber or Timestamp,
else the callback URL's event_key, and a DTMF event with none throws.
Parameters
ctx
Raw webhook request context.
Returns
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:439
Speaks text using escaped TwiML; raw interpolation is an explicit compatibility option.
Parameters
input
Returns
Promise<void>
Implementation of
verifyWebhook()
verifyWebhook(
ctx):WebhookVerificationResult
Defined in: packages/agentos/src/io/channels/telephony/providers/twilio.ts:248
Verify an incoming Twilio webhook request using HMAC-SHA1.
Algorithm (step by step)
- Extract the
X-Twilio-Signatureheader from the request. - Parse the request body as URL-encoded form data.
- Sort the keys in case-sensitive code-unit order, as twilio-node's
getExpectedTwilioSignaturedoes. A locale-aware sort putsCalledbeforeCallSidand fails every real voice webhook. - 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,Digits,SequenceNumberorTimestamprepeats with different values is refused. - Compute
HMAC-SHA1of the signed string using the auth token as the key. - Base64-encode the digest and compare it to the header value.
- Repeat with the URL with and without its port, as twilio-node does (see twilioUrlVariants); any match is valid.
Parameters
ctx
Raw webhook request context.
Returns
Verification result with valid: true if the signature matches.