Class TelnyxVoiceProvider

Telnyx voice call provider.

Uses the Telnyx Call Control v2 API for outbound call initiation and in-call actions (hangup, speak). Webhook verification uses Ed25519 public key signing.

Example

const provider = new TelnyxVoiceProvider({
  apiKey:       process.env.TELNYX_API_KEY!,
  connectionId: process.env.TELNYX_CONNECTION_ID!,
  publicKey:    process.env.TELNYX_PUBLIC_KEY,   // optional
});

Implements

Constructors

constructor

Methods

verifyWebhook parseWebhookEvent initiateCall hangupCall playTts

Properties

name

Constructors

constructor

Methods

verifyWebhook

  • verifyWebhook(ctx): WebhookVerificationResult

  • Verify an incoming Telnyx webhook using Ed25519 signature verification.

    Algorithm (step by step)

    1. If no public key is configured, skip verification (return valid: true). This supports development environments without cryptographic setup.
    2. Extract X-Telnyx-Timestamp and X-Telnyx-Signature-Ed25519 headers.
    3. Decode the signature from base64 into a raw byte Buffer.
    4. Construct the signed payload: "{timestamp}|{rawBody}".
    5. Decode the SPKI public key from base64.
    6. Call crypto.verify(null, payload, { key, format: 'der', type: 'spki' }, signature).
    7. Return the verification result.

    Parameters

    Returns WebhookVerificationResult

    Verification result. Returns { valid: true } when no public key is configured (development mode).

parseWebhookEvent

  • parseWebhookEvent(ctx): WebhookParseResult

  • Parse a Telnyx webhook JSON body into normalized NormalizedCallEvents.

    Telnyx sends all webhook payloads as JSON with a data.event_type discriminant field. The data.payload object contains call-specific fields like call_control_id, hangup_cause, digit, and result.

    Hangup cause mapping

    Telnyx's call.hangup event includes a hangup_cause field that must be inspected to determine whether the user or the system terminated the call:

    • normal_clearing / user_busy / originator_cancel -> call-hangup-user
    • All other causes (e.g., call_rejected, unallocated_number) -> call-completed

    Parameters

    Returns WebhookParseResult

    Parsed result containing zero or more normalized events.

initiateCall

  • initiateCall(input): Promise<InitiateCallResult>

  • Initiate an outbound call via the Telnyx Call Control v2 API.

    POSTs to /v2/calls with a JSON body containing the connection_id, phone numbers, and webhook URL. The mediaStreamUrl (if provided) is stored internally for use after the call is answered -- it is NOT sent in the initial call creation request because Telnyx requires streaming_start to be issued as a separate action after call.answered.

    Parameters

    Returns Promise<InitiateCallResult>

    Result containing the Telnyx call_control_id on success.

    Throws

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

hangupCall

playTts

  • playTts(input): Promise<void>

  • Speak text into a live call using Telnyx's text-to-speech speak action.

    POSTs a JSON body to /v2/calls/{id}/actions/speak with the text payload, voice (default 'female'), and language (default 'en-US').

    Parameters

    • input: PlayTtsInput

      TTS parameters (text, optional voice, call ID).

    Returns Promise<void>

Properties

Readonly name

name: "telnyx" = ...

Provider identifier, always 'telnyx'.

Settings

Member Visibility

Theme

On This Page

constructorverifyWebhookparseWebhookEventinitiateCallhangupCallplayTtsname