Skip to main content

Class: TelnyxVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:304

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​

Constructors​

Constructor​

new TelnyxVoiceProvider(config): TelnyxVoiceProvider

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:337

Parameters​

config​

TelnyxVoiceProviderConfig

Telnyx credentials and optional overrides. With allowUnverifiedWebhooks: true and no publicKey, the provider logs one warning and accepts webhooks unverified. That is decided here, once: a later change to config does not open the webhook.

Returns​

TelnyxVoiceProvider

Properties​

name​

readonly name: "telnyx"

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:306

Provider identifier, always 'telnyx'.

Implementation of​

IVoiceCallProvider.name

Accessors​

webhookIdentity​

Get Signature​

get webhookIdentity(): "legacy" | "stable-v1"

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:309

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​

answerCall()​

answerCall(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:568

Answer an inbound call. CallManager.answerInboundCall calls it once the host has admitted the call.

In the carrier profile it POSTs to /v2/calls/{id}/actions/answer with a command_id named after the call, so Telnyx ignores the command if it is sent again for that call, and, given a media stream URL, the stream settings the dial request carries (stream_url, the inbound track streamed as PCMU, bidirectional RTP with PCMU), so the stream starts with the answer.

The legacy profile sends nothing: its host answers the call.

Parameters​

input​

AnswerCallInput

The inbound call and its media stream URL.

Returns​

Promise<void>

Throws​

When Telnyx answers the command with a status outside 2xx.

Implementation of​

IVoiceCallProvider.answerCall


hangupCall()​

hangupCall(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:591

Hang up an active call via the Telnyx Call Control hangup action.

POSTs an empty JSON body to /v2/calls/{call_control_id}/actions/hangup. Telnyx will terminate the call and fire a call.hangup webhook.

Parameters​

input​

HangupCallInput

Contains the Telnyx call_control_id to hang up.

Returns​

Promise<void>

Throws​

In the carrier profile, when Telnyx answers the command with a status outside 2xx; CallManager writes it to the console.

Implementation of​

IVoiceCallProvider.hangupCall


initiateCall()​

initiateCall(input): Promise<InitiateCallResult>

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:530

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 streamed as PCMU 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​

input​

InitiateCallInput

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

Returns​

Promise<InitiateCallResult>

Result containing the Telnyx call_control_id on success.

Throws​

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

Implementation of​

IVoiceCallProvider.initiateCall


onCallAnswered()​

onCallAnswered(input): Promise<void>

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:624

Set up a call Telnyx reports answered. CallManager calls it once per call, when an event first moves the call to answered.

In the carrier profile a notify call with a message speaks it: a POST to /v2/calls/{id}/actions/speak with the message as payload, the voice given (female when none is), language en-US, a command_id named after the call, so Telnyx ignores the command if it is sent again for that call, and a client_state tag. It does not hang up: the command's call.speak.ended webhook, with that tag and status completed, parses to notify-message-spoken, on which CallManager hangs the call up. A conversation call gets no command: an outbound call's dial request carries the media stream URL.

The legacy profile sends nothing, and its host sends the commands.

Parameters​

input​

CallAnsweredInput

The answered call.

Returns​

Promise<void>

Throws​

When Telnyx answers the command with a status outside 2xx.

Implementation of​

IVoiceCallProvider.onCallAnswered


parseWebhookEvent()​

parseWebhookEvent(ctx): WebhookParseResult

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:443

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​

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/telnyx.ts:651

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>

Implementation of​

IVoiceCallProvider.playTts


verifyWebhook()​

verifyWebhook(ctx): WebhookVerificationResult

Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:371

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​

ctx​

WebhookContext

Raw webhook request context.

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.

Implementation of​

IVoiceCallProvider.verifyWebhook