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; without a public key every webhook is refused, unless the provider is constructed with allowUnverifiedWebhooks for local development.

Example

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

Implements

Accessors

webhookIdentity

Constructors

constructor

Methods

verifyWebhook parseWebhookEvent initiateCall hangupCall playTts

Properties

name

Accessors

webhookIdentity

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, refuse the webhook in either profile, unless the provider was constructed with allowUnverifiedWebhooks and no key, for local development: then skip verification and return valid: true.
    2. Extract the Telnyx-Timestamp and Telnyx-Signature-Ed25519 headers (or their X- prefixed forms).
    3. Decode the signature from base64 into a raw byte Buffer.
    4. Construct the signed payload: "{timestamp}|{rawBody}".
    5. Decode the public key from base64 into DER SPKI (telnyxPublicKeyDer).
    6. Call crypto.verify(null, payload, { key, format: 'der', type: 'spki' }, signature).
    7. Reject a timestamp older than webhookToleranceSec (default 300).
    8. Return the verification result.

    Parameters

    Returns WebhookVerificationResult

    Verification result. Without a public key it is { valid: false } in either profile, or { valid: true } when the provider was constructed with allowUnverifiedWebhooks and no key.

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

    A body without a data object holding a payload object yields no events. In carrier mode each event carries a stable id from stableCarrierEvents; a DTMF event's occurrence is the webhook's data.id, else its data.occurred_at, else the callback URL's event_key.

    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. In carrier mode a mediaStreamUrl is sent as stream_url with the inbound track and bidirectional PCMU RTP. Legacy mode neither sends nor keeps it: the host starts a stream with the streaming_start 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

webhookIdentityconstructorverifyWebhookparseWebhookEventinitiateCallhangupCallplayTtsname