Skip to main content

Configure inbound calls with Telnyx

Step-by-step guide to route Telnyx phone numbers to Agoralia and let your AI agents answer incoming calls.

Overview​

With Agoralia you don't buy phone numbers directly from us. Instead, you connect the numbers you already own on providers like Twilio, Telnyx, MessageBird, Plivo, Vonage, Sinch, or your own SIP PBX.

This guide shows how to:

  • Connect an existing Telnyx number to Agoralia
  • Configure Telnyx so that when someone calls your number, Agoralia answers
  • Test that your AI agent picks up the call correctly

If you haven't connected your Telnyx account or phone numbers yet, start from the Telnyx integration page inside Agoralia.

Prerequisites​

Before you start, make sure you have:

  • ✅ A verified Telnyx account
  • ✅ At least one active Telnyx phone number
  • ✅ An AI agent created and published in Agoralia
  • ✅ A phone number record in Agoralia that is linked to your Telnyx number
  • ✅ Admin or editor access to your Agoralia workspace

1. Enable inbound calls in Agoralia​

  1. Sign in to your Agoralia workspace
  2. Go to Settings → Phone numbers
  3. Find the Telnyx number you want to use and click Edit
  4. Scroll to the Inbound calls section
  5. Enable the toggle "Enable inbound calls"
  6. In Inbound call agent, select the AI agent that should answer incoming calls on this number
  7. (Optional) Configure the Event webhook URL if you want Agoralia to notify your backend about call events

Agoralia will now show you a Telnyx Call Control Webhook URL, specific to this phone number and tenant.

2. Copy the Telnyx webhook URL from Agoralia​

Still in the Edit Phone Number page in Agoralia:

  1. In the Inbound calls section, look for the Telnyx block

  2. You'll see a field like:

    https://api.agoralia.app/webhooks/telnyx/voice/{tenantId}/{phoneNumberId}

  3. Click Copy to copy the URL to your clipboard

You will paste this URL into Telnyx in the next step.

3. Configure your Telnyx number​

  1. Log in to your Telnyx Portal

  2. Go to Numbers → My Numbers

  3. Click the phone number you have linked to Agoralia

  4. Scroll to the Call Control section

  5. Under Connection Settings:

    • Set Call Control App to Webhook
    • In the Webhook URL field, paste the Telnyx Call Control Webhook URL you copied from Agoralia
    • Set the method to POST

  6. Click Save at the bottom of the page

From now on, when someone calls this Telnyx number, Telnyx will send the call event to Agoralia.

4. How the call flow works​

Once everything is configured:

  1. Caller dials your Telnyx number

  2. Telnyx sends a webhook to:

    https://api.agoralia.app/webhooks/telnyx/voice/{tenantId}/{phoneNumberId}

  3. Agoralia:

    • Validates the tenant and phone number
    • Checks that inbound is enabled and an agent is assigned
    • Creates a CallRecord for tracking
    • Starts the configured voice engine
    • Responds to Telnyx with Call Control JSON that connects the call to the AI agent

  4. Telnyx connects the audio stream to the AI engine

  5. Your AI agent answers the call and handles the conversation in real time

You don't need to write any Call Control JSON yourself – Agoralia generates it for you.

5. Test your setup​

Once Telnyx and Agoralia are configured:

  1. Use a different phone (mobile or landline)

  2. Call the Telnyx number you have configured

  3. Expect the following behavior:

    • The call is picked up automatically after a short ring
    • You hear the AI agent greeting (according to the agent's prompt)
    • The call appears in Agoralia under Calls with direction inbound

If the call is not answered or the AI doesn't speak, see the troubleshooting section below.

Troubleshooting​

The call rings but no one answers​

Check the following:

  • In Agoralia:

    • In the Edit Phone Number page, ensure "Enable inbound calls" is turned on
    • Make sure an Inbound call agent is selected

  • In Telnyx:

    • Confirm the Webhook URL matches exactly the one from Agoralia
    • Confirm the method is POST

Telnyx shows connection errors​

This usually means the URL is wrong or the IDs don't match.

  • Re-copy the webhook URL from the Inbound calls section in Agoralia
  • Make sure there are no extra spaces or missing parts
  • Confirm that the tenant and phoneNumberId in the path are valid in your workspace

The call is answered but the AI is silent​

Possible causes:

  • The selected agent is not published
  • The voice engine configuration for that agent is incomplete
  • There is an upstream issue with the voice provider

What to try:

  • In Agoralia, open the Agent edit page and:

    • Confirm the agent is published
    • Test the agent using the Test / Preview feature

  • If preview works but phone calls don't, contact support with:

    • Call timestamp
    • Caller number
    • Telnyx Call ID

The wrong agent answers the call​

  • In Edit Phone Number, double-check the selected Inbound call agent
  • If you changed the agent recently, save the configuration again and test with a new call
  • Make sure you're editing the correct phone number (Telnyx may have multiple similar numbers)

Next steps​

Once inbound calls are working with Telnyx, you can:

  • Add more numbers and assign them to different agents (sales, support, after-hours, etc.)
  • Configure event webhooks in Agoralia to send call outcomes to your backend or CRM
  • Use the Calls section in Agoralia to review transcripts and improve your agents

If you also use other providers, see: