Class TwilioVoiceProvider

constructor

• new TwilioVoiceProvider(config): TwilioVoiceProvider

• Parameters

  • config: TwilioVoiceProviderConfig

    Twilio credentials and optional overrides.

  Returns TwilioVoiceProvider

verifyWebhook

• verifyWebhook(ctx): WebhookVerificationResult

• 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 all key-value pairs alphabetically by key.
  4. Build the signed string: start with the full URL, then append each key + value (no delimiters between pairs).
  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.

  Parameters

  • ctx: WebhookContext

    Raw webhook request context.

  Returns WebhookVerificationResult

  Verification result with valid: true if the signature matches.

parseWebhookEvent

• parseWebhookEvent(ctx): WebhookParseResult

• 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.

initiateCall

• initiateCall(input): Promise<InitiateCallResult>

• 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.

hangupCall

• hangupCall(input): Promise<void>

• 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>

playTts

• playTts(input): Promise<void>

• 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>

Readonly name