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
readonlyname:"telnyx"
Defined in: packages/agentos/src/io/channels/telephony/providers/telnyx.ts:306
Provider identifier, always 'telnyx'.
Implementation of
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
The inbound call and its media stream URL.
Returns
Promise<void>
Throws
When Telnyx answers the command with a status outside 2xx.
Implementation of
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
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
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
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
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
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/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
TTS parameters (text, optional voice, call ID).
Returns
Promise<void>
Implementation of
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)
- If no public key is configured, refuse the webhook in either profile,
unless the provider was constructed with
allowUnverifiedWebhooksand no key, for local development: then skip verification and returnvalid: true. - Extract the
Telnyx-TimestampandTelnyx-Signature-Ed25519headers (or theirX-prefixed forms). - Decode the signature from base64 into a raw byte Buffer.
- Construct the signed payload:
"{timestamp}|{rawBody}". - Decode the public key from base64 into DER SPKI (telnyxPublicKeyDer).
- Call
crypto.verify(null, payload, { key, format: 'der', type: 'spki' }, signature). - Reject a timestamp older than
webhookToleranceSec(default 300). - Return the verification result.
Parameters
ctx
Raw webhook request context.
Returns
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.