AMI (Asterisk Manager Interface) configuration

AMI (Asterisk Manager Interface) configuration

Manager, i.e. AMI (Asterisk Manager Interface), is an interface that enables remote management of the Asterisk telephone system. This is a very important element that allows for automation and remote control of the system. One could even go so far as to say that it is a kind of CTI (Computer Telephony Integration), i.e. a service enabling the integration of the telephone system with other external services and systems. The Manager interface in Asterisk is available via TCP port 5038 (default) and supports the AMI (Asterisk Manager Interface) protocol. Thanks to this, the API can be operated from various programming languages such as PHP, Python, Java, Ruby, Perl and many others. In the post below, we will show you how to use this tool in practice, also on various popular telecommunications platforms such as FreePBX

Table of Contents

1) Manager Configuration

The manager does not need to be installed separately after the standard Asterisk installation. AMI is an embedded programming interface available with the main Asterisk suite. This means it is available with the standard Asterisk installation and configuration. AMI is supported by appropriate configuration of the manager.conf file, which defines access parameters, permissions and behavior for remote connections to the AMI interface. In this file you can configure users, passwords, access to various commands and operations. After proper configuration, the AMI will be ready for use, and you will be able to use its interface with external applications that can connect to Asterisk via the appropriate protocol and port. Let’s now configure our manager.conf file using our favorite nano notebook. Full documentation can be found at github repository
					nano /etc/asterisk/manager.conf
Here are the most important parameters in the manager.conf file and their meaning:
  1. enabled: Specifies whether the AMI should be enabled (yes) or disabled (no). If disabled, external applications will not be able to connect to the AMI.
  2. webenabled: Specifies whether the AMI is accessible via HTTP. Setting to yes allows communication via HTTP.
  3. port: Specifies the port number on which the AMI will listen.
  4. bindaddr: Specifies the IP address on which the AMI will listen. You can set it to to listen on all available network interfaces.
  5. displayconnects: Specifies whether connection information will be displayed in the Asterisk system console. Setting it to yes will display AMI connection notifications in the console.
  6. secret: This is the password that external applications use to authenticate to the AMI. Each application must know this password to connect.
  7. deny: Specifies IP addresses that are prohibited for connecting to the AMI.
  8. permit: Specifies the IP addresses that are allowed to connect to the AMI. You can use permit and deny to define access policies.
  9. read: Specifies a list of permissions for read operations on the AMI. The value can be all, system, call, log, verbose, agent, user, config, command, dtmf, report, originate, cdr, accounting.
  10. write: Specifies a list of permissions for AMI write operations. Like read, values can be different types of operations.
  11. writetimeout: Specifies the time to wait for confirmation of a write operation. After this time, the save operation will be canceled.
Let’s analyze an example configuration for two different Manager users

1a) Basic options – [general] section

In the example below, we have a [general] section in which we will define global settings for all Manager users. They may be overwritten in individual user sections.
enabled = yes
webenabled = no
bindaddr =
port = 5038
displayconnects = yes
tlsenable = no

The enabled = yes option make the AMI interface to be enabled. The bindaddr = option tells us that it will be available to all IP addresses on the default port 5038 (port = 5038 option). Additionally, we want connection information to be displayed in Asterisk system console (option displayconnects = yes), but we do not want the interface to be available via the www (option webenabled = no) and we decide that the Manager will not support connections using TLS and all connections will be unencrypted. (option tlsenable = no).

It's worth noting that setting "bindaddr =" may be unsafe if the Manager interface is not properly secured with a password or IP addresses that have access. In this case, malicious actors can gain unauthorized access to the interface and make changes to the system.

1b) Encryption connection with TLS – [general] section

tlsenable = yes
Setting "tlsenable = yes" means that the Manager interface will support encrypted connections. This requires setting a few additional parameters. The "tlsbindaddr=" setting indicates that the Manager interface will listen for encrypted connections on port 5039 on all IP addresses where the server it is running is accessible Asterisk system. The tlscertfile option indicates where the system should look for the certificate, and the tlsprivatekey option indicates where to look for the private key. If the second option is not available, the system will look for the private key in the certificate file.

For more information on how to create certificates, see this post.​

1c) Additional options – [general] section

allowmultiplelogin = no
debug = on
The allowmultiplelogin = no option will not allow multiple connections to the Manager using the same login (the default setting is enabled – yes). The debug = on option enables debugging mode for the Manager API. Asterisk then prints additional diagnostic information about the interface’s activities. This option may be helpful if you experience any connection or operation problems with the Manager API. (default is off – off)

2) Manager configuration – user sections

The next sections in the manager.conf file will define the users. Here are two examples:
secret = StrongPa$$w0rd1
deny =
permit =
read = all
write = all
writetimeout = 1000
displayconnects = no

secret = StrongPa$$w0rd2
read = system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,user,config,command,reporting,originate,message

We have two users defined: user and remote_user with passwords provided in the secret option. For the user user, we overwrite the permissions to connect from any IP address that we have allowed in the general section. The deny = option blocks connection from any IP address, then the permit = option allows the user to only connect from the local IP address, which is the address where asterisk is currently running (localhost). The writetimeout = 1000 option allows us to extend the inactivity time on a connected Asterisk session with a user. We give it in milliseconds. This prevents disconnection on slower connections. The displayconnects = no option overrides the default yes value defined in the general section. The read = all and write = all  options allow this user to receive all system events and send all available commands to the Asterisk system. The remote_user user has global permissions of the general section and additionally has specific rights to write and read information. We will explain their meaning in the next section. In the Asterisk console we can check the status of connected users. If we have only made changes now, we explain how to reload the configuration later in the post. Let’s show existing users first:
					manager show users

Next, let’s look at the configuration of one of our users
					manager show user remote_user


3) List of Manager permissions

For the AMI read and write options, we have the following options:
					read = all,system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan,agi,cc,aoc,test,security
write = all, system,call,agent,user,config,command,reporting,originate,message,agi,aoc,test,message
The meaning of each information class is as follows:
					all - all events described below and even those not listed here are available.
system - general system information and the ability to run system management commands such as Shutdown, Restart and Reload. This class also includes the ability to manipulate the dialplan using commands such as DialplanExtensionAdd and DialplanExtensionRemove.
call - Information about channels and the ability to set information in the current channel.
log - logging information. (Defined but not yet used).
verbose - full information. (Defined but not yet used).
agent - Information about queues and agents and the ability to add queues and agents to queues
user - permission to send and receive UserEvents.
config - ability to save and read configuration files.
command - ability to send commands available in the Asterisk console
dtmf - receiving DTMF events
reporting - ability to receive information about the system status
cdr - reading events related to CDRs
dialplan - receiving NewExten and VarSet events.
originate - permission to create new connections
agi - execution of AGI commands
cc - receiving Call Completion events
aoc - sending and receiving AOC (Advice Of Charge) messages.
test - Ability to receive and send TestEvent type notifications to the Asterisk Test Suite module. Will only work if the TEST_FRAMEWORK compiler flag is defined
security - reading security events
message - permission to send text messages

4) Managing the Manager service

Each change to the manager.conf configuration file requires reloading the module from the Asterisk console.
					asterisk -rx "manager reload"
We can also display the current Manager configuration.
					asterisk -rx "manager show settings"
					Global Settings:
  Manager (AMI):             Yes
  Web Manager (AMI/HTTP):    No
  TCP Bindaddress: 
  HTTP Timeout (seconds):    60
  TLS Enable:                No
  TLS Bindaddress:           Disabled
  TLS Certfile:              asterisk.pem
  TLS Privatekey:
  TLS Cipher:
  Allow multiple login:      Yes
  Display connects:          Yes
  Timestamp events:          No
  Channel vars:
  Debug:                     No

The list of available commands is as follows. (for convenience, we will enter the Asterisk console)
					asterisk -r
					manager show commands
					pbx*CLI> manager show commands
  Action                                       Synopsis
  ------                                       --------
  AbsoluteTimeout                              Set absolute timeout.
  AgentLogoff                                  Sets an agent as no longer logged
  Agents                                       Lists agents and their status.
  AGI                                          Add an AGI command to execute by
  AOCMessage                                   Generate an Advice of Charge mess
  Atxfer                                       Attended transfer.
  BlindTransfer                                Blind transfer channel(s) to the
  Bridge                                       Bridge two channels already in th
  BridgeDestroy                                Destroy a bridge.
  BridgeInfo                                   Get information about a bridge.
  BridgeKick                                   Kick a channel from a bridge.
  BridgeList                                   Get a list of bridges in the syst
  BridgeTechnologyList                         List available bridging technolog
  BridgeTechnologySuspend                      Suspend a bridging technology.
  BridgeTechnologyUnsuspend                    Unsuspend a bridging technology.
  CancelAtxfer                                 Cancel an attended transfer.
  Challenge                                    Generate Challenge for MD5 Auth.
  ChangeMonitor                                Change monitoring filename of a c
  Command                                      Execute Asterisk CLI Command.
  ConfbridgeKick                               Kick a Confbridge user.
  ConfbridgeList                               List participants in a conference
  ConfbridgeListRooms                          List active conferences.
  ConfbridgeLock                               Lock a Confbridge conference.
  ConfbridgeMute                               Mute a Confbridge user.
  ConfbridgeSetSingleVideoSrc                  Set a conference user as the sing
  ConfbridgeStartRecord                        Start recording a Confbridge conf
  ConfbridgeStopRecord                         Stop recording a Confbridge confe
  ConfbridgeUnlock                             Unlock a Confbridge conference.
  ConfbridgeUnmute                             Unmute a Confbridge user.
  ControlPlayback                              Control the playback of a file be
  CoreSettings                                 Show PBX core settings (version e
  CoreShowChannels                             List currently active channels.
  CoreStatus                                   Show PBX core status variables.
  CreateConfig                                 Creates an empty file in the conf
  DBDel                                        Delete DB entry.
  DBDelTree                                    Delete DB Tree.
  DBGet                                        Get DB Entry.
  DBGetTree                                    Get DB entries, optionally at a p
  DBPut                                        Put DB entry.
  DeviceStateList                              List the current known device sta
  DialplanExtensionAdd                         Add an extension to the dialplan
  DialplanExtensionRemove                      Remove an extension from the dial
  Events                                       Control Event Flow.
  ExtensionState                               Check Extension Status.
  ExtensionStateList                           List the current known extension
  FAXSession                                   Responds with a detailed descript
  FAXSessions                                  Lists active FAX sessions
  FAXStats                                     Responds with fax statistics
  Filter                                       Dynamically add filters for the c
  GetConfig                                    Retrieve configuration.
  GetConfigJSON                                Retrieve configuration (JSON form
  Getvar                                       Gets a channel variable or functi
  Hangup                                       Hangup channel.
  IAXnetstats                                  Show IAX Netstats.
  IAXpeerlist                                  List IAX Peers.
  IAXpeers                                     List IAX peers.
  IAXregistry                                  Show IAX registrations.
  ListCategories                               List categories in configuration
  ListCommands                                 List available manager commands.
  LocalOptimizeAway                            Optimize away a local channel whe
  LoggerRotate                                 Reload and rotate the Asterisk lo
  Login                                        Login Manager.
  Logoff                                       Logoff Manager.
  MailboxCount                                 Check Mailbox Message Count.
  MailboxStatus                                Check mailbox.
  MessageSend                                  Send an out of call message to an
  MixMonitor                                   Record a call and mix the audio d
  MixMonitorMute                               Mute / unMute a Mixmonitor record
  ModuleCheck                                  Check if module is loaded.
  ModuleLoad                                   Module management.
  Monitor                                      Monitor a channel.
  MuteAudio                                    Mute an audio stream.
  Originate                                    Originate a call.
  Park                                         Park a channel.
  ParkedCalls                                  List parked calls.
  Parkinglots                                  Get a list of parking lots
  PauseMonitor                                 Pause monitoring of a channel.
  Ping                                         Keepalive command.
  PJSIPNotify                                  Send a NOTIFY to either an endpoi
  PJSIPQualify                                 Qualify a chan_pjsip endpoint.
  PJSIPRegister                                Register an outbound registration
  PJSIPShowAors                                Lists PJSIP AORs.
  PJSIPShowAuths                               Lists PJSIP Auths.
  PJSIPShowContacts                            Lists PJSIP Contacts.
  PJSIPShowEndpoint                            Detail listing of an endpoint and
  PJSIPShowEndpoints                           Lists PJSIP endpoints.
  PJSIPShowRegistrationInboundContactStatuses  Lists ContactStatuses for PJSIP i
  PJSIPShowRegistrationsInbound                Lists PJSIP inbound registrations
  PJSIPShowRegistrationsOutbound               Lists PJSIP outbound registration
  PJSIPShowResourceLists                       Displays settings for configured
  PJSIPShowSubscriptionsInbound                Lists subscriptions.
  PJSIPShowSubscriptionsOutbound               Lists subscriptions.
  PJSIPUnregister                              Unregister an outbound registrati
  PlayDTMF                                     Play DTMF signal on a specific ch
  PlayMF                                       Play MF digit on a specific chann
  PresenceState                                Check Presence State
  PresenceStateList                            List the current known presence s
  QueueAdd                                     Add interface to queue.
  QueueChangePriorityCaller                    Change priority of a caller on qu
  QueueLog                                     Adds custom entry in queue_log.
  QueueMemberRingInUse                         Set the ringinuse value for a que
  QueuePause                                   Makes a queue member temporarily
  QueuePenalty                                 Set the penalty for a queue membe
  QueueReload                                  Reload a queue, queues, or any su
  QueueRemove                                  Remove interface from queue.
  QueueReset                                   Reset queue statistics.
  QueueRule                                    Queue Rules.
  QueueStatus                                  Show queue status.
  QueueSummary                                 Show queue summary.
  QueueWithdrawCaller                          Request to withdraw a caller from
  Redirect                                     Redirect (transfer) a call.
  Reload                                       Send a reload event.
  SendText                                     Sends a text message to channel.
  Setvar                                       Sets a channel variable or functi
  ShowDialPlan                                 Show dialplan contexts and extens
  SIPnotify                                    Send a SIP notify.
  SIPpeers                                     List SIP peers (text format).
  SIPpeerstatus                                Show the status of one or all of
  SIPqualifypeer                               Qualify SIP peers.
  SIPshowpeer                                  show SIP peer (text format).
  SIPshowregistry                              Show SIP registrations (text form
  SKINNYdevices                                List SKINNY devices (text format)
  SKINNYlines                                  List SKINNY lines (text format).
  SKINNYshowdevice                             Show SKINNY device (text format).
  SKINNYshowline                               Show SKINNY line (text format).
  SorceryMemoryCacheExpire                     Expire (remove) ALL objects from
  SorceryMemoryCacheExpireObject               Expire (remove) an object from a
  SorceryMemoryCachePopulate                   Expire all objects from a memory
  SorceryMemoryCacheStale                      Marks ALL objects in a sorcery me
  SorceryMemoryCacheStaleObject                Mark an object in a sorcery memor
  Status                                       List channel status.
  StopMixMonitor                               Stop recording a call through Mix
  StopMonitor                                  Stop monitoring a channel.
  UnpauseMonitor                               Unpause monitoring of a channel.
  UpdateConfig                                 Update basic configuration.
  UserEvent                                    Send an arbitrary event.
  VoicemailRefresh                             Tell Asterisk to poll mailboxes f
  VoicemailUsersList                           List All Voicemail User Informati
  VoicemailUserStatus                          Show the status of given voicemai
  WaitEvent                                    Wait for an event to occur.
We will receive dozens of commands that we can use in practice. The syntax of a specific command, for example ping, can be obtained by running the example command below:
					manager show command ping

Action: Ping
[ActionID:] <value>

Keepalive command.

A 'Ping' action will ellicit a 'Pong' response. Used to keep the manager
connection open.

    ActionID for this transaction. Will be returned.

[See Also]
Not available


[List Responses]

[Final Response]

After configuring the entire service, we will be able to see AMI queries in the console. If you establish a connection to listen to PBX events, it is worth considering adding additional filters in manager.conf to slightly limit the amount of information received.
					;eventfilter=Event: Newchannel
;eventfilter=Channel: (PJ)?SIP/(james|jim|john)-
;eventfilter=!Channel: DAHDI/
You can apply the above filters globally or to selected users. For more information, please refer to the documentation cited at the beginning.

5) Manager configuration in FreePBX

FreePBX does not give us direct access to the headquarters, but in the control panel on the website there are options for configuring and managing the Manager. Log in to the freePBX management console and select Settings -> AsteriskManagerUsers
Here we can edit existing users and their permissions or add a new one. We will do this by clicking + Add Manager. We will get a screen as below, where we can set the parameters that we previously defined in the manager.conf file
In the Permissions tab, we will set read and write permissions for a given user.
Of course, after setting all the parameters, we click the Apply Config button and our manager is configured in FreePBX In the following posts we will discuss how to compile and execute AMI queries using PHP, Node.JS and similar…
If you would like tomonitor everything that is happening on your PBX, try our proprietary software VOIPERO Installation and configuration takes a few minutes and the system is currently availabletotally free Read what our VOIPERO system can do in terms of live monitoring and reporting of Asterisk-based VoIP systems. The AMI manager interface just described above is mainly used in Voipero.
Share this post

Do you have questions or you need an offer?

Contact us!

Most popular

Related Posts

We Have Launched

Monitoring & Reporting of Your VoIP Server