AI Load Balancers
An AI load balancer groups several AI assistants behind one destination. Each call goes to one member chosen by the strategy (round robin, priority or percentage). With Follow Through on, a member that fails is skipped and the next one is tried. When no member can take the call, the fallback runs: an extension, ring group, IVR menu, another AI assistant, a call queue, another AI load balancer, or hang up.
Purpose
Use a load balancer to:
- share call volume between assistants or providers;
- keep a backup assistant ready when the primary one fails;
- test a new assistant on a share of the calls;
- send callers to people when every assistant fails.
Prerequisites
- At least one active AI assistant. Inactive assistants cannot be added. See AI Assistants.
- A fallback destination, if you do not want callers to be hung up on. It must exist and be active.
- You are the Owner or a PBX Admin to create, edit or delete. Reporters can open the page read-only.
Permissions
| Action | Owner | PBX Admin | PBX User | Reporter | Supervisor |
|---|---|---|---|---|---|
| See AI Load Balancers in the sidebar | Yes | Yes | No | Yes (read-only) | No |
| List and view (API) | Yes | Yes | Yes | Yes | Yes |
| Create, edit, activate or deactivate | Yes | Yes | No | No | No |
| Delete | Yes | Yes | No | No | No |
How a call moves through a load balancer
A failure is a provider leg that ends busy, no answer, failed, canceled or with an unknown status. Members already tried for the call are skipped (the list is kept for one hour). See Strategies, Follow Through and Fallback for the details of each step.
Designs
Primary and backup
- Strategy Priority Based, with the primary assistant at the top of the list.
- Follow Through on, so a busy or failed primary moves the call to the next member.
- Members from different providers, so one provider's outage does not stop every member.
- A Ring Group, Call Queue or PBX User Extension fallback, so the last resort is a person.
Gradual roll-out of a new assistant
- Strategy Percentage Based.
- Start with 10 % on the new assistant and 90 % on the current one. The dialog offers weights in steps of 5 %.
- Raise the share as you gain confidence. Saving the load balancer applies the new weights to the next call.
Even load
- Strategy Round Robin across assistants that do the same job.
- Follow Through on, so a failing member does not lose the caller.
Example: Acme Corp front desk
The demo organization has a load balancer Front Desk AI Pool: Round Robin over the assistants Aria - Front Desk Receptionist (VAPI) and Max - Support Triage (Retell), with Hang Up as the fallback. Routing a phone number to it alternates callers between the two assistants.

Workflows
Create a load balancer
Who can do this: Owner, PBX Admin.
- Open Apps and Security → AI Configuration → AI Load Balancers in the sidebar.
- Click Create AI Load Balancer (top right). The Create AI Load Balancer dialog opens.
- Enter a Name of at least 2 characters, for example
Front Desk AI Pool. - Under Distribution Strategy, click Round Robin, Priority Based or Percentage Based.
- Under AI Assistant Members, click Add Member once per assistant. Each click adds the next active assistant that is not yet a member and shows the toast Added name to load balancer. To use a different assistant, pick it in the member's dropdown. Click X on a member to remove it.
- For Priority Based, order the members; for Percentage Based, set the weights.
- Turn Follow Through on (Enabled) to try the next member when one fails, or leave it Disabled.
- Under Fallback Action, choose the Action and, when it needs one, the Destination (for example a ring group of people). The action starts as Hang Up ("Call will end").
- Click Create AI Load Balancer.
The dialog closes, the toast AI Load Balancer created successfully appears and the load balancer is listed as Active. It is now offered everywhere an AI load balancer can be chosen. A new load balancer must have a real fallback: the create dialog does not offer Disconnect.
If something is missing, the dialog stays open and shows the problem under the field, for example Name must be at least 2 characters, At least one AI Assistant member is required or Fallback ring group is required.

Add Member is disabled when every active assistant is already a member; the dialog then says All available AI Assistants have been added to this load balancer. A load balancer has at most 50 members.
Order members for Priority Based
Who can do this: Owner, PBX Admin.
- In the create or edit dialog, select Priority Based. Each member gets a drag handle.
- Drag the members by the handle. The top member is the first choice; the next one is used only when the first cannot take the call (with Follow Through on) or is inactive.
- Click Create AI Load Balancer or Save Changes.

Set weights for Percentage Based
Who can do this: Owner, PBX Admin.
- In the create or edit dialog, select Percentage Based. Each member gets a Weight dropdown (0 % to 100 % in steps of 5). A new member starts at 100 %.
- Set the weights so that Total Distribution shows 100 %, for example 80 % for the current assistant and 20 % for the one under test.
- Click Create AI Load Balancer or Save Changes.
If the total is not 100 %, saving stops with Percentage distribution must equal 100% (currently: N%). Please adjust the weights.

Find a load balancer
Who can do this: Owner, PBX Admin, Reporter.
- Type in Search AI Load Balancers... to filter by name.
- Use the Strategy filter (All Strategies, Round Robin, Priority Based, Percentage Based) and the Status filter (All Status, Active, Disabled).
- Turn on the Unprovisioned filter to see only load balancers whose fallback is disconnected.
- Click the refresh button to reload, and the Strategy or Status column header to sort. The list shows 25 load balancers per page.
Reporters see a Read-Only badge, no Create AI Load Balancer button and no row actions.
Edit a load balancer
Who can do this: Owner, PBX Admin.
- Click the load balancer's row or name. The Edit AI Load Balancer dialog opens.
- Change the name, strategy, members, Follow Through or Fallback Action.
- Click Save Changes.
The toast AI Load Balancer updated successfully appears. Saving replaces the member list with the one in the dialog, and new weights apply from the next call. If another person is saving the same load balancer at that moment, the save is refused with "Load balancer is currently being modified. Please try again."

Disconnect the fallback
Who can do this: Owner, PBX Admin.
- Open the load balancer's Edit AI Load Balancer dialog.
- Under Fallback Action, choose Disconnect (offered on the edit dialog only).
- Click Save Changes.
This stores "Destination unavailable": callers who reach the fallback hear "Destination doesn't exist" and the call ends. The load balancer then shows the Unprovisioned badge in the list and in the dialog title, and the Unprovisioned filter on the list finds it. Pick a real fallback to clear the badge. A new load balancer always needs a real fallback.
The same state appears after a user is deleted whose extension was the fallback.
Activate or deactivate
Who can do this: Owner, PBX Admin.
Click the Active or Disabled badge in the Status column. The change is saved at once and the toast AI Load Balancer updated successfully appears.
An inactive load balancer takes no calls: every call sent to it is disconnected with a spoken message, on every path (phone number, AI Load Balancer extension, IVR option or failover, business-hours action, and ring group, call queue or load balancer fallbacks). Most paths say "The AI load balancer you are trying to reach is unavailable. Goodbye."; an IVR option says "Destination is no longer available." and a fallback says that no agents or AI assistants are available. Its own fallback is not used; the fallback only runs when an active load balancer's members cannot take the call.
Delete a load balancer
Who can do this: Owner, PBX Admin.
- Click the delete (trash) action on the row.
- The Delete AI Load Balancer dialog asks: Are you sure you want to delete "name"? This action cannot be undone.
- Click Delete.
The toast AI Load Balancer deleted successfully appears and the row disappears.

If anything still points at the load balancer, the delete is refused and the Cannot delete: still in use dialog lists every place: phone numbers, IVR options and failovers, business-hours actions, ring-group, call-queue and AI load balancer fallbacks, extensions of type AI Load Balancer and auto-dialer campaigns. Change those, then delete again. Call history never blocks a delete.
Where a load balancer can be used
- Phone Numbers: routing type AI load balancer.
- IVR Menus: an option target or the failover.
- Business Hours: the open-hours or closed-hours action.
- Ring Groups and Call Queues: the fallback.
- Another AI load balancer: its fallback (see Fallback).
- Extensions: an extension of type AI Load Balancer.
- Campaign Manager: campaigns can connect answered calls to a load balancer.
While any of those point at it, it cannot be deleted (see Delete a load balancer).
Fields
| Field | Required | Limits and default | Meaning |
|---|---|---|---|
| Name | Yes | 2 to 255 characters; unique within the organization | Shown in lists and destination pickers |
| Distribution Strategy | Yes | Round Robin, Priority Based or Percentage Based. Default: Round Robin | How the member for each call is chosen |
| Members | Yes | 1 to 50 active AI assistants; each assistant once | The assistants that take calls |
| Weight | Percentage Based only | 0 to 100 % in steps of 5 in the dialog. Default for a new member: 100 | Share of calls for the member |
| Follow Through | No | Off by default | Try the next member when one fails |
| Fallback Action | Yes | PBX User Extension, Ring Group, IVR Menu, AI Assistant, Call Queue, AI Load Balancer or Hang Up. Default: Hang Up | What happens when no member can take the call |
| Status | No | Active or Disabled (inactive in the API). Default: Active. Change it from the list | Calls to an inactive load balancer are disconnected with a message (its fallback is not used) |
| Description | No (API only) | Up to 1000 characters | Free text. The dialog does not show it |
Strategies
| Strategy | How the member is chosen | Typical use |
|---|---|---|
| Round Robin | Members take turns, in list order. The turn counter is kept in Redis; if Redis is unavailable, a member is picked at random | Even load across equal assistants |
| Priority Based | Always the first active member in list order. Drag members to set the order | A primary assistant with backups |
| Percentage Based | Weighted random choice. In the dialog the weights must add up to 100 % ("Percentage distribution must equal 100%"). A member with weight 0 is never chosen while others have weight | A/B tests and gradual roll-outs |
Only members whose assistant is active take part. An assistant you deactivate later is skipped automatically.
Follow Through
| Follow Through | When the chosen assistant's call fails |
|---|---|
| On | The next untried member is chosen with the same strategy, and so on until every member was tried. Then the fallback runs |
| Off | The fallback runs at once |
A call counts as failed when the provider leg ends busy, no answer, failed, canceled or with an unknown status. It applies to SIP and WebSocket members; a Dummy Test member has nothing to fail. The list of members already tried for a call is kept for one hour.
Fallback
| Fallback Action | Result |
|---|---|
| PBX User Extension | Rings the chosen extension. The dialog lists active PBX User extensions |
| Ring Group | Sends the call to the ring group, which rings its members with its own strategy and uses its own fallback. If the group is missing or inactive, the call ends |
| IVR Menu | Plays the menu |
| AI Assistant | Connects one more assistant, without Follow Through. It cannot be a member of the same load balancer ("Circular reference detected") |
| Call Queue | Puts the caller in the call queue, so people answer |
| AI Load Balancer | Hands the call to another load balancer's selection. It cannot be this one. Saving is refused (422) if the chain of AI Load Balancer fallbacks would ever return to this balancer: A to A, A to B to A, A to B to C to A and so on. The message names the loop ("Fallback loop detected"). If a loop still exists at call time, the call ends |
| Hang Up | Ends the call (the default) |
Call Queue and AI Load Balancer need a target: saving without one is refused. The fallback target must belong to your organization and be active when you save.
The fallback runs only for an active load balancer. On the edit dialog, Disconnect sets the fallback to "Destination unavailable" and marks the load balancer Unprovisioned (see Disconnect the fallback).
Common errors
| Message (summary) | What it means | What to do |
|---|---|---|
| A load balancer with this name already exists in your organization | The name is taken, also by a deleted load balancer | Choose another name |
| At least one AI Assistant member is required | The member list is empty | Add a member |
| Only active AI assistants can be added to load balancers | A member is inactive | Activate the assistant or remove it |
| Percentage distribution must equal 100% (currently: N%) | The weights do not add up to 100 | Adjust the weights |
| Fallback … must be active | The fallback target is inactive | Activate it or pick another |
| Circular reference detected: Fallback AI assistant cannot be a member | The fallback assistant is also a member | Pick a different fallback assistant |
| A load balancer cannot fall back to itself | The AI Load Balancer fallback is the same load balancer | Pick a different one |
| Choose a destination | You tried to create with "Destination unavailable" (API) | Pick a fallback. Disconnect is for edits only |
| Load balancer is currently being modified | Two saves at the same time | Try again |
| Cannot delete: still in use | Routing configuration points at the load balancer | Change the listed references, then delete |
Key data fields
ai_assistant_load_balancers
| Column | Notes |
|---|---|
id | Primary key |
organization_id | Tenant scope |
name | Unique within the organization, deleted rows included |
strategy | round_robin, priority or percentage |
follow_through | Boolean |
status | active or inactive |
fallback_action | extension, ring_group, ivr_menu, ai_assistant, call_queue, ai_load_balancer, hangup or unavailable |
fallback_extension_id, fallback_ring_group_id, fallback_ivr_menu_id, fallback_ai_assistant_id, fallback_call_queue_id, fallback_ai_load_balancer_id | Only the one that matches the action is set |
deleted_at | Deletes are soft deletes |
ai_assistant_load_balancer_members
| Column | Notes |
|---|---|
load_balancer_id, ai_assistant_id | Each assistant once per load balancer |
position | List order (round robin) |
priority | Lower is tried first (priority strategy). The dialog sets it from the list order |
weight | 0 to 100 (percentage strategy) |
status | active or inactive |
Related API endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/ai-assistant-load-balancers | List. Filters: strategy, status, search, unprovisioned=1 |
| POST | /v1/ai-assistant-load-balancers | Create. Rejects "Destination unavailable" |
| GET | /v1/ai-assistant-load-balancers/{id} | One load balancer with members |
| PUT | /v1/ai-assistant-load-balancers/{id} | Update. Sending members replaces them all |
| DELETE | /v1/ai-assistant-load-balancers/{id} | Delete. Returns 409 with the list of uses when in use |
Scoped API keys use the ai-assistant-load-balancers resource (see API Keys). The MCP server has list_ai_load_balancers and get_ai_load_balancer.
See the OPBX REST API reference for full schemas.
Monitoring and troubleshooting
- Call Logs show each call to the number that routes to the load balancer.
- With the centralized logging stack enabled, the routing log names the member chosen for each call and every failover step: search for
AiLoadBalancerRoutingStrategyto see which member was chosen for a call, and forALBS Follow Throughto follow a failover.
Common causes of "callers always get the fallback":
- every member's assistant is inactive;
- the provider rejects the call (check the assistant's phone number or agent ID).
If callers hear "The AI load balancer you are trying to reach is unavailable." and are disconnected, the load balancer is inactive: activate it.
Related modules
- AI Assistants — the members
- Extensions — AI Load Balancer extensions
- Phone Numbers — route a number to a load balancer
- Auto Dialer — campaigns can connect answered calls to a load balancer