Skip to content
TriedDocs
Telephony

Telnyx

How Tried buys numbers from Telnyx, wires them to LiveKit SIP, and uses Telnyx for SMS and number reputation.

Telnyx is Tried's default number provider. When the platform has a Telnyx API key, POST /create-phone-number buys a number on the platform's Telnyx account and Tried connects it to LiveKit SIP for you: there is nothing to set up in the Telnyx portal per number. Telnyx is also the SMS provider and the source of number reputation for branded caller ID and verified numbers.

Needs keys

Everything on this page needs TELNYX_API_KEY. Without it, a mock provider returns fake numbers and records each request in the provider operation log (GET /telephony/operations).

Platform setup#

This is a one-time setup by whoever runs the Tried deployment.

Env var Required Purpose
TELNYX_API_KEY yes Telnyx API v2 key.
TELNYX_SIP_USERNAME, TELNYX_SIP_PASSWORD yes Any strong credential. Written to the Telnyx FQDN connection and to each number's LiveKit outbound trunk.
TELNYX_ANCHORSITE no Media anchor site on the connection. Use Sydney, Australia for AU numbers. Default Latency.
TELNYX_CONNECTION_ID no Use an existing connection instead of creating one. Pair with TELNYX_OUTBOUND_VOICE_PROFILE_ID.
TELNYX_MESSAGING_PROFILE_ID no Messaging profile for SMS.
TELNYX_PUBLIC_KEY for SMS Ed25519 public key to verify inbound webhooks.
TELNYX_ENTERPRISE_ID for caller trust Enterprise for Number Reputation enrolment.
TELNYX_INBOUND_ALLOWED_ADDRESSES no CIDRs allowed to send INVITEs for Telnyx numbers. Empty by default.

What happens when you buy a Telnyx number#

  1. GET /available_phone_numbers finds a number by country, area code (national_destination_code), toll-free type and contains. Only voice-capable numbers are returned.
  2. POST /number_orders buys it.
  3. On the first purchase (unless TELNYX_CONNECTION_ID is set), Tried creates an outbound voice profile and an FQDN connection: TCP, +E.164 caller and dialled number formats, codecs G722, PCMU and PCMA, your SIP credentials and anchor site. It adds LIVEKIT_SIP_URI port 5060 as the connection's FQDN. The connection is reused for later numbers.
  4. The number is assigned to the connection.
  5. LiveKit trunks and a dispatch rule are created. The outbound trunk points at sip.telnyx.com with your Telnyx SIP credentials and the X-Telnyx-Username header, which makes Telnyx answer with a digest challenge.

See Get a phone number for the request fields and prices.

Calls per second#

Telnyx numbers default to 4 calls per second (DEFAULT_CPS_TELNYX). Set Calls per second on the number's Routing and SIP card up to 16, the dashboard's ceiling for Telnyx. Higher account limits are arranged with Telnyx.

SMS#

Point the Telnyx messaging profile webhook at https://<api>/telnyx/webhook. Tried verifies the telnyx-signature-ed25519 and telnyx-timestamp headers with TELNYX_PUBLIC_KEY and handles message.received (inbound texts) and delivery status events. Outbound SMS and MMS go through POST /v2/messages. See SMS.

Caller trust#

Branded caller ID and verified numbers enrol the number in Telnyx Number Reputation (TELNYX_ENTERPRISE_ID) and read its spam risk on refresh. The carrier display name itself is registered in the Telnyx portal. See Caller ID and trust.

Inbound caller details#

Telnyx sends P-Attestation-Indicator and X-Telnyx-CNAM on inbound calls. Tried stores them on the call as stir_shaken_attestation and caller_cnam.

Release#

Deleting a Telnyx number in Tried deletes its LiveKit objects and releases the number with DELETE /phone_numbers/:id. A failed release is logged and the number is still removed from Tried, so check the Telnyx portal if a release error appears in the logs.