Skip to main content

Configure inbound calls with MessageBird

Step-by-step guide to route MessageBird 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 MessageBird number to Agoralia
  • Configure MessageBird 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 MessageBird account or phone numbers yet, start from the MessageBird integration page inside Agoralia.

Prerequisites​

Before you start, make sure you have:

  • ✅ A verified MessageBird account
  • ✅ At least one active MessageBird phone number
  • ✅ An AI agent created and published in Agoralia
  • ✅ A phone number record in Agoralia that is linked to your MessageBird 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 MessageBird 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 MessageBird Webhook URL, specific to this phone number and tenant.

2. Copy the MessageBird webhook URL from Agoralia​

Still in the Edit Phone Number page in Agoralia:

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

  2. You'll see a field like:

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

  3. Click Copy to copy the URL to your clipboard

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

3. Configure your MessageBird number​

  1. Log in to your MessageBird Dashboard

  2. Go to Numbers → Your Numbers

  3. Click the phone number you have linked to Agoralia

  4. Scroll to the Voice section

  5. Under Call Settings:

    • Set Voice Webhook URL to the URL you copied from Agoralia
    • Set the method to POST

  6. Click Save to apply the changes

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

4. How the call flow works​

Once everything is configured:

  1. Caller dials your MessageBird number

  2. MessageBird sends a webhook to:

    https://api.agoralia.app/webhooks/messagebird/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 MessageBird with call flow JSON that connects the call to the AI agent

  4. MessageBird 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 flow JSON yourself – Agoralia generates it for you.

5. Test your setup​

Once MessageBird and Agoralia are configured:

  1. Use a different phone (mobile or landline)

  2. Call the MessageBird 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 MessageBird:

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

MessageBird shows webhook 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
    • MessageBird 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 (MessageBird may have multiple similar numbers)

Next steps​

Once inbound calls are working with MessageBird, 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: