Bridgeside AI
← All posts

How to Set Up a FreePBX AI Agent, Step by Step

Put an AI voice agent on FreePBX with one custom dialplan entry, a Custom Destination, an AMI user and a firewall rule, then hand callers to a ring group or queue.

FreePBX already does the hard parts of running a phone system: trunks, inbound routes, IVRs, ring groups, queues and recordings. A FreePBX AI agent should slot into that, not sit beside it. This guide walks through the whole setup on a working FreePBX server, file by file and menu by menu: a custom dialplan entry, a Custom Destination you can pick anywhere FreePBX asks for a destination, an AMI user for transfers and hangups, the firewall, and transfers back to a ring group or queue. Your SIP trunks do not change and there is no module to install.

If you want the architecture background first, read how to add AI voice agents to Asterisk and FreePBX. This post is the hands-on version.

How a FreePBX AI agent call flows

  1. A call reaches a destination you choose in FreePBX, for example an inbound route, an IVR option or a queue failover.
  2. That destination sends the call to extension 85 plus a campaign's three digit dial code in the from-internal context.
  3. The custom dialplan answers, asks Bridgeside for a UDP port for this call with CURL, and dials UnicastRTP to that port. Audio flows both ways as G.711 ulaw.
  4. The agent talks to the caller using the campaign's script. When it decides to transfer or end the call, it sends an AMI Redirect or Hangup for the caller's channel.
  5. After the call, a signed webhook can deliver the outcome, a short summary and the collected answers to your CRM.

Your PBX stays in charge of the call throughout. The agent is a destination, like a ring group.

Before you start

You need root shell access to the FreePBX server, a Bridgeside account with at least one campaign (each campaign shows a three digit dial code on its page, for example 001), and Asterisk 15 or newer. Current FreePBX releases ship much newer Asterisk versions, but check:

asterisk -rx "core show version"
asterisk -rx "module show like chan_rtp"
asterisk -rx "core show function CURL"

chan_rtp provides the UnicastRTP channel and CURL requests the port. Both must be present.

Also make sure nothing on the PBX already uses the numbers 85000 to 85999, such as five digit extensions or a feature code.

Step 1. Add the dialplan to extensions_custom.conf

FreePBX rewrites most of its Asterisk config files when you click Apply Config, but it leaves /etc/asterisk/extensions_custom.conf alone. That is where hand-written dialplan belongs. The [from-internal-custom] context in that file is included in from-internal, so anything you put there can be dialled from extensions and reached from a Custom Destination.

On the Bridgeside portal, open the Dialers page and copy the Asterisk dialplan. It already contains your organization's token and the server address. Paste it under a [from-internal-custom] header, or below the existing header if the file already has one. Your copy has real values where this one has placeholders:

[from-internal-custom]
exten => _85XXX,1,Answer()
  same => n,Set(GW=https://app.bridgeside.ai)
  same => n,Set(PORT=${CURL(${GW}/api/asterisk/rtp?token=YOUR_TOKEN&agent=${EXTEN:2}&channel=${URIENCODE(${CHANNEL})}&lead=${URIENCODE(${CALLERID(name)})}&phone=${URIENCODE(${CALLERID(num)})})})
  same => n,GotoIf($["${PORT}" = ""]?fail)
  same => n,Dial(UnicastRTP/162.35.111.14:${PORT}/c(ulaw),,b(voicebot-jb^s^1))
  same => n,Hangup()
  same => n(fail),Playback(all-circuits-busy-now)
  same => n,Hangup()

[voicebot-jb]
exten => s,1,Set(JITTERBUFFER(adaptive)=default)
  same => n,Return()

What the lines do: ${EXTEN:2} strips the 85 so the remaining digits pick the campaign. The CURL request carries the channel name (so the agent can transfer or hang up this exact call later) and the caller ID. If the request is refused, for example because the token is wrong or the account has no credit left, PORT comes back empty and the caller hears the all circuits busy message instead of silence. The b() option runs the small [voicebot-jb] routine on the new channel, which adds an adaptive jitter buffer so audio arriving over the internet plays smoothly.

Reload and confirm Asterisk sees it:

asterisk -rx "dialplan reload"
asterisk -rx "dialplan show 85001@from-internal"

Step 2. Create a Custom Destination

In the FreePBX GUI go to Admin, then Custom Destinations, and add one:

  • Target: from-internal,85001,1 (context, extension, priority; use your own dial code)
  • Description: something you will recognise in a dropdown, such as "AI agent, sales"

Submit and Apply Config. The agent now appears under Custom Destinations in every destination picker in FreePBX. If you run several campaigns, create one Custom Destination per campaign. They all use the same dialplan entry.

Step 3. Send calls to the agent

Anything in FreePBX that takes a destination can now reach the agent:

  • Inbound route: Connectivity, Inbound Routes, pick the DID, then Set Destination to the Custom Destination. Good for a dedicated number or a campaign line.
  • IVR option: Applications, IVR, add an entry (for example "press 2 for a quote") whose destination is the agent.
  • Queue failover: Applications, Queues, set the Fail Over Destination so callers who wait too long reach the agent instead of voicemail.
  • Ring group no answer: Applications, Ring Groups, set the destination if no answer.
  • After hours: Applications, Time Conditions, send the not matching branch to the agent.

Step 4. Create an AMI user in manager_custom.conf

Raw RTP carries audio and nothing else, so the agent needs the Asterisk Manager Interface to transfer and hang up. FreePBX writes manager.conf itself, but it includes manager_custom.conf, which it does not touch. Add a block there:

[bridgeside]
secret = a-long-random-secret
deny = 0.0.0.0/0.0.0.0
permit = 162.35.111.14/255.255.255.255
read = call
write = system,call,originate

Then reload and check:

asterisk -rx "manager reload"
asterisk -rx "manager show user bridgeside"
asterisk -rx "manager show settings"

The agent uses only three things on this connection: the hangup event, Hangup and Redirect. The last command shows the address and port AMI listens on. If it only listens on 127.0.0.1, Bridgeside cannot reach it; change that through FreePBX rather than editing manager.conf by hand, because FreePBX rewrites that file.

Step 5. Open the FreePBX firewall

If the FreePBX Firewall module is active, go to Connectivity, Firewall, Networks and add 162.35.111.14/32 in the Trusted zone. AMI is still protected by the permit line and the secret. If you run Intrusion Detection, make sure the address is not banned after a few failed logins while you test.

Outbound from the PBX, UDP 5001 to 5999 (call audio, one port per call) and TCP 443 (the port request) must reach Bridgeside. Most servers allow outbound traffic already, but check any cloud security group or upstream firewall too. Never open 5038 to the internet.

Step 6. Register the PBX and set up transfers

On the portal's Dialers page, add a dialer:

FieldValue
TypeAsterisk (plain, FreePBX, Issabel)
Host or IPThe PBX's public IP. Bridgeside connects here for AMI and recognises the PBX's calls by this source address
AMI user, secret, portbridgeside, your secret, 5038
Transfer contextfrom-internal

The transfer context matters. The default for Asterisk type dialers is VICIdial's trunkinbound, which does not exist on FreePBX. The row should show connected within a few seconds.

Then open the campaign's Transfer tab and enter the ring group or queue number, for example 600 for a sales ring group or 400 for a queue. When the agent decides a caller should speak to a person, it tells the caller and sends an AMI Redirect that moves the live channel to 600 in from-internal. The ring group rings, or the caller joins the queue with its normal hold music and announcements. The caller never hangs up. For how the hand-off should sound, see warm transfer versus blind transfer.

Step 7. Test it

  1. From a desk phone, dial 85001. The campaign greeting should play.
  2. Watch asterisk -rvvv while you call. You should see the CURL return a port and Dial(UnicastRTP/...) start.
  3. Ask to speak to someone. The ring group or queue should take the call.
  4. Call the DID from a mobile phone to test the inbound route path.
  5. Check the portal's Calls page for the transcript and outcome.
SymptomLikely cause
All circuits busyCURL failed: token, outbound 443 blocked, campaign paused or no credit
Answers, then silenceOutbound UDP 5001 to 5999 blocked, or the PBX's IP differs from the registered host
Choppy agent audioThe [voicebot-jb] context was not pasted
Transfer does nothingAMI not connected, or transfer context still trunkinbound

Results, recordings and data

FreePBX has no lead database, so call results go out by webhook. Set a URL on the campaign's Dispositions tab and choose events: call.started, call.transferred, call.appointment and call.ended, each signed with HMAC. The ended event carries the disposition, a short summary, typed answers to your questions and the transcript.

Call recording stays in FreePBX under your existing inbound route and extension settings. Bridgeside does not store call audio. It keeps transcripts for the 1 to 90 days your organization chooses, then redacts or deletes them.

FAQ

Is there a FreePBX AI agent module to install?

Not for this setup. The FreePBX AI agent described here uses standard Asterisk pieces that are already on the server: a dialplan entry, the UnicastRTP channel, the CURL function and an AMI user. Nothing is added to the module admin page.

Does an AI agent for FreePBX need a new SIP trunk?

No. Calls arrive on your existing trunks and reach the agent through a normal destination. The audio between the PBX and Bridgeside travels as RTP over the internet, separate from your carrier.

Can the FreePBX AI voice agent transfer to a queue or ring group?

Yes. Put the queue or ring group number on the campaign's Transfer tab and set the dialer's transfer context to from-internal. The live call is redirected, so the caller stays connected.

Will Apply Config overwrite the changes?

No. FreePBX leaves extensions_custom.conf and manager_custom.conf alone, which is why both are used here. Custom Destinations are stored by FreePBX itself.

What does a FreePBX AI agent cost?

Bridgeside is pay as you go with no monthly fee, from 4.5 cents a minute on larger plans, and 10 channels start at $49 a month. Carrier charges stay with your carrier. See pricing for every plan.

Try it on one route

Pick one low-risk destination, such as after-hours calls or a queue failover, and point it at a test campaign. The Asterisk integration page has the short version of this guide, and the AI agent architectures for Asterisk post explains why this design uses RTP from the dialplan. You get 60 free minutes with no card at app.bridgeside.ai.

Put an AI agent on your dialer

60 free minutes, no card, one dialplan entry.