AMI connection

BeePanel follows the PBX live through the Asterisk Manager Interface (AMI): the live panel, call events, extension and queue state, and call actions such as transfers all run over one AMI connection. History, reports, users, and the other local features keep working when the connection is down.

What the installer prepares

On the PBX, the installer creates an AMI identity named beepanel in its own file, /etc/asterisk/manager_beepanel.conf:

it accepts connections only from the server's own address;
it can read system, call, and agent events, and write reporting, system, call, originate, and agent actions;
it receives only the events BeePanel uses;
its secret is random and never printed.

To load that file, the installer adds one marked block to /etc/asterisk/manager_custom.conf when that file exists and manager.conf includes it, and to /etc/asterisk/manager.conf otherwise:

; BEGIN BEEPANEL MANAGED MANAGER INCLUDE
#include manager_beepanel.conf
; END BEEPANEL MANAGED MANAGER INCLUDE

It then reloads the manager; Asterisk is not restarted. Nothing else in the PBX's manager configuration changes, and uninstalling BeePanel removes the block and the file again. Setup fills in the identity's address and username, and keeps the secret on the server.

Before you start

Asterisk 12 or newer.
The AMI listener enabled: enabled = yes under [general] in /etc/asterisk/manager.conf.

If the listener is off during installation, the installer still prepares the identity and prints:

warning: AMI listener is disabled in /etc/asterisk/manager.conf; connection not verified

Set enabled = yes, change nothing else, reload the manager, and then verify the connection in setup:

asterisk -rx "manager reload"

Verifying the connection in setup

When the Configuration screen opens, setup checks the prepared connection on its own and shows the result on the AMI connection row: BeePanel connects, signs in, subscribes to the events it needs, and lists the endpoints. After a failure, or to change the address, open the row, correct the values, and choose Verify connection. If the address is not on the server itself, BeePanel cannot verify that the connection is protected, and asks you to accept that risk before you continue.

You can also clear the row's checkbox and finish setup without AMI; the live features then stay unavailable until you set the connection up in Settings.

Changing the connection

Prerequisite: a user allowed to manage BeePanel.

Open Management > Settings, and choose Edit on the AMI connection row under PBX connection.
Correct AMI address (host and port, such as 127.0.0.1:5038), AMI username, or both. Leave AMI secret empty to keep the stored secret, which BeePanel never shows again, or type a new one.
Choose Validate and save.

BeePanel runs the same checks as setup before it switches to the new connection. If they fail, the current connection stays in use.

To use an AMI user of your own, give it the same read and write permissions as the prepared identity, and do not filter out the events BeePanel needs.

Checking the result

The AMI row on the Status page shows Connected.
The live panel shows your extensions and trunks.

When the connection drops, BeePanel reconnects on its own. Meanwhile the live panel shows PBX connection lost, and its state is refreshed as soon as the connection is back.

Common problems

BeePanel could not reach the AMI address. Check the address and network access, then try again.

Nothing answers at the address. Check that the AMI listener is enabled, that the port is right (5038 by default), and that no firewall blocks it.

AMI rejected the username or secret. Check the identity and try again.

The username or secret does not match the identity on the PBX. Type the secret again, or check the identity in /etc/asterisk/manager_beepanel.conf.

This AMI identity cannot supply the live events and extension state BeePanel requires. Check the identity's AMI permissions.

BeePanel signed in but cannot receive the events or list the endpoints it needs. Give the identity the permissions listed above; an event filter on the identity can cause the same message.

The connection is open but no events have arrived for a while.

The Status page marks the connection Stale. Check that Asterisk is running; BeePanel reconnects when the connection recovers.