Telnyx
Set up Telnyx as your telephony provider for outbound and inbound voice calls with zoxaAI.
What you'll learn
How to configure Telnyx as a telephony provider in zoxaAI, including the Call Control Application auto-creation, webhook public key setup for signature verification, and inbound call routing.
Telnyx
Telnyx is a cloud communications platform built on a global private network. zoxaAI integrates with Telnyx for both outbound and inbound calling using their Call Control API.
Provider Details
| Feature | Value |
|---|---|
| Provider name | telnyx |
| Audio format | mulaw |
| Sample rate | 8,000 Hz |
| Call transfer | No |
| Auto-create application | Yes |
| Webhook signature verification | Yes (Ed25519 public key) |
| Account ID field | connection_id |
Prerequisites
- A Telnyx account (sign up at telnyx.com)
- At least one Telnyx phone number
Credentials
| Field | Where to Find It | Sensitive | Required | Description |
|---|---|---|---|---|
| API Key | Mission Control Portal > API Keys | Yes | Yes | Your Telnyx API Key (starts with KEY) |
| Call Control App ID | Mission Control Portal > Call Control > Applications | No | No | Your Call Control Application ID (connection_id). If left blank, zoxaAI auto-creates one on save. |
| Webhook Public Key | Mission Control Portal > Keys & Credentials > Public Key | No | Recommended | Used to verify webhook signatures from Telnyx. Without it, inbound calls may be rejected. |
Setup
Open the Telephony Page
Navigate to Telephony in the zoxaAI sidebar.
Add a New Configuration
Click Add Configuration. Select Telnyx from the provider dropdown.
Enter Your API Key
Paste your API Key from the Telnyx Mission Control Portal. It starts with KEY.
Configure Call Control App ID (optional)
Leave the Call Control App ID blank to have zoxaAI auto-create a Call Control Application. Or enter an existing one if you prefer to manage it yourself.
Add Webhook Public Key (recommended)
Paste your Webhook Public Key from Mission Control Portal > Keys & Credentials > Public Key. This is strongly recommended for production use.
Name and Save
Give the configuration a name (e.g., "Telnyx Production") and click Save.
Add Phone Numbers
Right after you save, zoxaAI opens the new configuration and fetches the voice numbers on your Telnyx account. Click Add next to the ones you want, or Add all. You can fetch again any time with Fetch from Telnyx in the Phone Numbers section.
To add a number by hand instead, click Add phone number and enter it in E.164 format:
+14155552671
+12125551234Only active numbers are listed. Telnyx routes a number's inbound calls through the connection it is assigned to, so a number on another connection shows an info icon: assign it to this configuration's Call Control App in the Telnyx portal to receive inbound calls through zoxaAI.
Webhook Public Key
The webhook public key is used to verify that inbound webhooks are genuinely from Telnyx using Ed25519 signature verification. Without it, webhook signature verification will fail and inbound calls will be rejected.
Find Your Public Key
Log in to the Telnyx Mission Control Portal. Go to Keys & Credentials in the left sidebar. Copy the Public Key.
Add to zoxaAI
Paste the public key into the Webhook Public Key field in your zoxaAI Telnyx configuration.
Missing webhook public key
If you have a Telnyx configuration without a webhook public key, zoxaAI displays a warning banner on the Telephony page. Inbound calls will fail signature verification without this key.
Auto-Created Application
When you do not provide a Call Control App ID, zoxaAI automatically creates a Telnyx Call Control Application during the save process. The auto-created application has:
- Application name:
zoxa-<random-id>(e.g.,zoxa-a3b2c1d4e5f6) - Webhook Event URL:
https://your-domain.com/api/v1/telephony/run
This means inbound calls work immediately for any number assigned to the auto-created application.
Outbound Calls
Telnyx outbound calls use the Call Control API. Audio is streamed over WebSocket in 8 kHz mulaw format.
| Source | Description |
|---|---|
| Test calls | Place a test call from the agent editor |
| API calls | Use POST /api/v1/call with your API key |
| Campaigns | Bulk outbound dialing across a contact list |
Inbound Calls
Telnyx fully supports inbound calling. If you used the auto-created application, inbound calls work immediately.
If you are using a pre-existing Call Control Application, configure it manually:
Open Mission Control Portal
Go to the Telnyx Mission Control Portal and navigate to Call Control > Applications.
Set Webhook Event URL
Click your application and set:
- Webhook Event URL:
https://your-domain.com/api/v1/telephony/run
Assign an Agent
In the zoxaAI dashboard, go to Telephony > your Telnyx configuration and open the phone number (or add it). Select the agent that should answer in the Inbound target dropdown and save.
See Inbound Calling for the full inbound routing guide.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Auto-create fails on save | Invalid API Key | Verify your API Key in the Telnyx Mission Control Portal |
| Inbound calls fail with signature error | Missing webhook public key | Add the public key from Mission Control > Keys & Credentials |
| Inbound calls not routing | Number not assigned to the Call Control Application | In Mission Control, assign the number to the auto-created (or manually configured) application |
| Outbound calls fail | No phone numbers added | Add at least one Telnyx number in E.164 format |