> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicerix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telnyx

> Connect Telnyx to Voicerix for outbound and inbound voice calls.

## Overview

Telnyx provides programmable voice via its Call Control API. Voicerix uses Call Control plus WebSocket media streaming to power your voice agents.

## Prerequisites

* A [Telnyx account](https://telnyx.com/)
* An **API Key** from the Telnyx Mission Control Portal
* A **Call Control Application** — or leave blank and Voicerix will auto-create one for you
* At least one Telnyx phone number assigned to that Call Control Application

## Configuration

### Step 1: Get Telnyx Credentials

1. Log in to the [Telnyx Mission Control Portal](https://portal.telnyx.com/)
2. Navigate to **API Keys** and create or copy an API Key
3. *(Optional)* Navigate to **Call Control** → **Applications**, open the application you'll use with Voicerix, and copy its **Connection ID** (Call Control App ID). Skip this if you want Voicerix to auto-create the application.
4. Navigate to **Numbers** → **My Numbers** and assign your phone numbers to the Call Control Application

### Step 2: Add Configuration in Voicerix

1. In Voicerix, go to **Integrations** and click **Add configuration**
2. Select **Telnyx** as your provider
3. Enter your credentials:
   * **API Key**
   * **Call Control App ID** *(optional — leave blank to auto-create)*
4. Click **Save Configuration**
5. Open the saved configuration and add at least one **phone number** in E.164 format (e.g. `+1234567890`)

<Note>
  If Voicerix auto-created the Call Control Application, you still need to assign your Telnyx numbers to that application in the Telnyx Portal under **Numbers** → **My Numbers**. The auto-created application is named `voicerix-<random>` — its Connection ID is shown on the saved configuration.
</Note>

### Step 3: Test

1. Go to **Agents**, open a workflow, and click **Test Call**
2. Check the call logs to confirm a successful connection

***

## Inbound Calling Setup

Telnyx delivers inbound webhooks at the **Call Control Application** level — the webhook URL is configured once on the application and applies to every number assigned to it. When you save an inbound workflow on a phone number in Voicerix, **Voicerix automatically pushes the webhook URL to your Call Control Application's `webhook_event_url`**. If Voicerix auto-created the application, the webhook URL is already set.

### Step 1: Assign an Inbound Workflow

1. In Voicerix, go to **Integrations** and open your Telnyx configuration
2. In the **Phone numbers** section, edit the number that should receive inbound calls
3. Set its **Inbound workflow** to the agent that should answer
4. Save

### Step 2: Verify in Telnyx Portal

1. Go to **Call Control** → **Applications** in the Telnyx Portal
2. Open the application whose Connection ID you configured in Voicerix
3. Under **Webhook Settings**, confirm:
   * **Webhook URL** is set to: `https://client.voicerix.ai/api/v1/telephony/inbound/run`
   * **HTTP Method** is `POST`
4. Make sure the phone numbers you want for inbound are assigned to this application

<Note>
  Voicerix pushes this URL automatically when you save the inbound workflow. The same URL is shared across every number on the Call Control Application — Voicerix matches the inbound call to the right agent using the called number's inbound workflow assignment. If the field is empty or shows a different URL, the auto-push failed — usually because the API Key or Connection ID is incorrect. Paste the URL manually, set the method to `POST`, and save.
</Note>

### Step 3: Test Inbound

1. Call your Telnyx number from another phone
2. Verify your voice agent answers and responds
3. Check call logs in both Voicerix and the Telnyx Portal

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid phone number error">
    Ensure phone numbers include the country code in E.164 format: `+1234567890`
  </Accordion>

  <Accordion title="Authentication failed">
    * Verify the API Key is correct and active
    * Check for extra spaces in the key
    * Ensure the key hasn't been revoked in the Telnyx Portal
  </Accordion>

  <Accordion title="Webhook signature validation failing">
    * Telnyx signs webhooks with Ed25519 — confirm the public key on the application hasn't changed
    * Verify the webhook URL matches what Telnyx sends
    * Check if you're behind a proxy that modifies request bodies
  </Accordion>

  <Accordion title="No audio on calls">
    * Verify the WebSocket connection is established
    * Check firewall rules for WebSocket traffic
    * Ensure the audio pipeline is configured correctly
  </Accordion>

  <Accordion title="Inbound calls aren't answered">
    * Verify the Call Control Application's webhook URL is set to `https://client.voicerix.ai/api/v1/telephony/inbound/run`
    * Ensure the webhook URL is publicly accessible
    * Confirm the called number is assigned to the same Call Control Application whose Connection ID is in Voicerix
    * Confirm the called number has an **Inbound workflow** assigned in Voicerix
  </Accordion>

  <Accordion title="Voice agent doesn't respond to inbound calls">
    * Confirm the phone number has an **Inbound workflow** assigned in Integrations
    * Verify the API Key matches the one stored in your Voicerix configuration
    * Verify WebSocket connection establishes successfully
    * Review call logs for error messages
  </Accordion>
</AccordionGroup>

## Best Practices

* Test your configuration with a single call before running campaigns
* Monitor the Telnyx Portal for usage and billing
* Use a dedicated Call Control Application for Voicerix so the shared webhook URL doesn't conflict with other systems