Telnyx Integration

Overview

Telnyx is a cloud communications platform that provides programmable voice via its Call Control API. Tigy AI's Telnyx integration uses Call Control plus WebSocket media streaming to power your voice agents.

Prerequisites

Before setting up Telnyx integration, you'll need:

• A Telnyx account
• An API Key from the Telnyx Mission Control Portal
• A Call Control Application (optional — leave the field blank in Tigy AI and we'll auto-create one for you on save, with the inbound webhook URL pre-set)
• At least one Telnyx phone number owned by the account
• Tigy AI instance running and accessible

Configuration

Step 1: Get Telnyx Credentials

1. Log in to the Telnyx Mission Control Portal
2. Navigate to API Keys and create (or copy) an API Key
3. (Optional) Navigate to Call Control → Applications and create (or open) the application you'll use with Tigy AI, then copy its Connection ID (Call Control App ID). Skip this if you want Tigy AI to auto-create the Call Control Application for you on save.
4. Make sure the phone numbers you want to use are present under Numbers → My Numbers. Tigy AI assigns a number to the configured Call Control Application when you attach an inbound agent to it.

Step 2: Configure in Tigy AI

1. Navigate to /telephony-configurations and click Add configuration
2. Select Telnyx as your provider
3. Enter your credentials:
   • API Key
   • Call Control App ID (Connection ID) — optional. Leave blank and Tigy AI will auto-create a Call Control Application on save (with the inbound webhook URL already configured) and store its Connection ID on this configuration.
4. Click Save Configuration
5. Open the configuration you just created and add at least one phone number in E.164 format.

Note

If Tigy AI auto-created the Call Control Application for you, its name is tigy-<random> and its Connection ID is shown on the saved configuration. Tigy AI assigns the number to this application when you save the inbound agent below.

Step 3: Test Your Configuration

1. Create a test agent
2. Click "Call" to verify connection
3. Check call logs for 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 agent on a phone number, Tigy AI assigns that number to your Call Control Application and pushes the webhook URL to its webhook_event_url (provided the credentials are correct). If Tigy AI auto-created the application during configuration save, the webhook URL is already set and only the number assignment is needed.

Step 1: Assign an Inbound Agent to the Phone Number

1. Go to /telephony-configurations and open your Telnyx configuration
2. In the Phone numbers section, edit the number that should receive inbound calls
3. Set its Inbound agent to the agent that should answer
4. Save

Step 2: Verify the Webhook URL on the Call Control Application

1. Go to Call Control → Applications in the Telnyx Portal
2. Open the application whose Connection ID you configured in Tigy AI
3. In Webhook Settings, confirm:
   • Webhook URL is set to: https://api.tigyai.com/api/v1/telephony/inbound/run
   • HTTP Method is POST
4. Make sure the phone numbers you want to use for inbound show this application in the Connection/Application column. Tigy AI performs this assignment when you save the inbound agent; you can re-save the agent if the sync previously failed.

Note

Tigy AI pushed this URL and assigned the number automatically when you saved the inbound agent in Step 1. The same URL is shared across every number on the Call Control Application — Tigy AI matches the inbound call to the right agent using the called number's inbound agent assignment. If the field is empty, shows a different URL, the number still shows Required for calls, or Tigy AI surfaced a sync warning on save, the provider sync failed — most often because the API Key, phone-number ownership, or Connection ID in Tigy AI is incorrect. Re-save the inbound agent after correcting the configuration. Tigy AI, replace api.tigyai.com with your backend domain.

Step 3: Verify Setup

• Ensure your Tigy AI instance is publicly accessible
• Verify any firewalls allow Telnyx's IP ranges

Test Inbound Calling

1. Call your configured Telnyx phone number from another phone
2. Verify your Tigy AI voice agent answers and responds
3. Check call logs in both Tigy AI dashboard and Telnyx Portal

Troubleshooting

Invalid phone number error

Ensure phone numbers include country code in E.164 format: `+1234567890`

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

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

No audio on calls

- Verify WebSocket connection is established - Check firewall rules for
WebSocket traffic - Ensure audio pipeline is configured correctly

Inbound calls aren't answered

- Verify the Call Control Application's webhook URL is set to
`https://api.tigyai.com/api/v1/telephony/inbound/run` - Ensure the webhook
URL is publicly accessible from the internet - Confirm the called number
is assigned to the same Call Control Application whose Connection ID is
configured in Tigy AI - Confirm the called number exists in your Tigy AI
telephony configuration and has an **Inbound agent** assigned - Verify
Tigy AI instance is running and responding

Voice agent doesn't respond to inbound calls

- Confirm the phone number has an **Inbound agent** assigned in
/telephony-configurations - Verify the API Key matches the one stored in
your Tigy AI telephony configuration - Verify WebSocket connection
establishes successfully - Review call logs for error messages

Best Practices

• Test your configuration with a single inbound call
• Monitor the Telnyx Portal for usage and billing
• Use a dedicated Call Control Application for Tigy AI so the shared webhook URL doesn't conflict with other systems