Passa al contenuto principale

Configure inbound calls with a custom SIP PBX

Step-by-step guide to route calls from your custom SIP PBX, Zadarma, or other SIP-based telephony systems to Agoralia AI agents.

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 your SIP PBX or custom telephony setup to Agoralia
  • Configure your SIP system so that when someone calls your numbers, Agoralia answers
  • Test that your AI agent picks up the call correctly

This setup works with any SIP-compatible PBX including Asterisk, FreeSWITCH, Zadarma, or custom SIP implementations.

Prerequisites​

Before you start, make sure you have:

  • ✅ A SIP PBX or custom telephony system (Asterisk, FreeSWITCH, Zadarma, etc.)
  • ✅ At least one phone number configured in your SIP system
  • ✅ An AI agent created and published in Agoralia
  • ✅ A phone number record in Agoralia marked as "custom" provider
  • ✅ 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 or create the phone number record for your custom setup and click Edit
  4. Set the Provider to "custom"
  5. Scroll to the Inbound calls section
  6. Enable the toggle "Enable inbound calls"
  7. In Inbound call agent, select the AI agent that should answer incoming calls on this number
  8. (Optional) Configure the Event webhook URL if you want Agoralia to notify your backend about call events

Agoralia will now show you an Inbound SIP Target, specific to this phone number and tenant.

2. Copy the SIP target from Agoralia​

Still in the Edit Phone Number page in Agoralia:

  1. In the Inbound calls section, look for the Custom SIP block

  2. You'll see a field like:

    sip:{tenantId}-{phoneNumberId}@inbound.agoralia.app

  3. Click Copy to copy the SIP target to your clipboard

You will configure your SIP PBX to forward calls to this SIP target.

3. Configure your SIP PBX​

The configuration depends on your specific SIP PBX system. Here are examples for common setups:

For Asterisk (extensions.conf)​

; In your extensions.conf
[agoralia-inbound]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
exten => _X.,n,Dial(PJSIP/${EXTEN}@agoralia-inbound)
exten => _X.,n,Hangup()

; In pjsip.conf or sip.conf
[agoralia-inbound]
type=endpoint
transport=transport-udp
context=agoralia-inbound
disallow=all
allow=ulaw,alaw
direct_media=no
connected_line_method=invite

For FreeSWITCH​

<!-- In your dialplan -->
<extension name="agoralia_inbound">
  <condition field="destination_number" expression="^(.*)$">
    <action application="bridge" data="sofia/external/$1@inbound.agoralia.app"/>
  </condition>
</extension>

For Zadarma​

  1. Log in to your Zadarma account

  2. Go to Settings → PBX → Routing

  3. Create a new routing rule for inbound calls

  4. Set the Destination to the SIP target you copied from Agoralia:

    sip:{tenantId}-{phoneNumberId}@inbound.agoralia.app

  5. Save the routing rule

Generic SIP PBX Configuration​

For any SIP PBX:

  1. Create a SIP trunk or outbound route pointing to inbound.agoralia.app

  2. Configure the dial pattern to forward all inbound calls to:

    sip:{tenantId}-{phoneNumberId}@inbound.agoralia.app

  3. Ensure your PBX allows outbound calls to this domain

4. How the call flow works​

Once everything is configured:

  1. Caller dials your phone number

  2. Your SIP PBX receives the call and forwards it to:

    sip:{tenantId}-{phoneNumberId}@inbound.agoralia.app

  3. Agoralia receives the SIP call:

    • Validates the tenant and phone number from the SIP URI
    • Checks that inbound is enabled and an agent is assigned
    • Creates a CallRecord for tracking
    • Starts the configured voice engine
    • Establishes the SIP/RTP connection with your PBX

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

The audio flows directly between your PBX and Agoralia's voice engine.

5. Test your setup​

Once your SIP PBX and Agoralia are configured:

  1. Use a different phone (mobile or landline)

  2. Call the phone number configured in your SIP PBX

  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​

Calls are not reaching Agoralia​

Check the following:

  • In Agoralia:

    • Confirm the phone number is marked as "custom" provider
    • Ensure "Enable inbound calls" is turned on
    • Make sure an Inbound call agent is selected

  • In your SIP PBX:

    • Confirm the SIP target matches exactly: sip:{tenantId}-{phoneNumberId}@inbound.agoralia.app
    • Check that your PBX can reach inbound.agoralia.app (port 5060 UDP/TCP)
    • Verify firewall rules allow SIP traffic

SIP registration/connection fails​

Common issues:

  • Firewall blocking: Ensure ports 5060 (SIP) and 10000-20000 (RTP) are open
  • NAT issues: If behind NAT, ensure proper SIP NAT traversal
  • Codec mismatch: Ensure your PBX supports G.711 (ulaw/alaw) codecs
  • DNS resolution: Confirm inbound.agoralia.app resolves correctly

The call connects but the AI is silent​

Possible causes:

  • The selected agent is not published
  • The voice engine configuration for that agent is incomplete
  • SIP/RTP audio is not flowing properly

What to try:

  • In Agoralia, open the Agent edit page and:

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

  • Check SIP logs on your PBX for RTP/media issues

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

    • Call timestamp
    • Caller number
    • SIP call logs from your PBX

Wrong tenant/phone number routing​

  • In Agoralia, double-check the SIP target format
  • Ensure the {tenantId} and {phoneNumberId} in the SIP URI are correct
  • If you changed the phone number configuration recently, restart your SIP PBX

Advanced Configuration​

Custom SIP Domains​

If you need to use a custom SIP domain instead of inbound.agoralia.app:

  1. Contact Agoralia support to set up a custom SIP domain
  2. Update your PBX configuration to use the custom domain
  3. Ensure DNS and firewall rules are updated accordingly

Multiple Numbers​

For multiple phone numbers:

  1. Create separate phone number records in Agoralia for each number

  2. Configure different SIP targets for each:

    sip:{tenantId}-{phoneNumberId1}@inbound.agoralia.app
    sip:{tenantId}-{phoneNumberId2}@inbound.agoralia.app

  3. Route calls accordingly in your PBX dialplan

Next steps​

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