Asterisk Manager Interface (AMI) allows a client program to connect to an Asterisk instance and issue commands or read events over a TCP/IP stream. This is particularly useful when the integrators try to track the state of a telephony client inside Asterisk.
A simple “key: value” command line-based interface is utilized for communication between the connecting client and the Asterisk PBX. Lines are terminated by using CR/LF. In this document, we will use the term “packet” to describe a set of “key: value” lines that are terminated by an extra CR/LF.
Some useful Asterisk Manager Interface information can be found in the following link:
The UCM6XXX provides restricted AMI access for users. In order to connect to Asterisk Manager Interface on UCM6XXX, please follow the steps below.
- Create new AMI user.
- Configure AMI ports for connection.
- Establish connection and authenticate the user.
This document introduces each step and necessary configurations in the following sections.
UCM6XXX series include UCM62xx series, UCM630x/A series, and UCM6510.
Please do not enable AMI on the UCM6XXX if it is placed on a public or untrusted network unless you have taken steps to protect the device from unauthorized access. It is crucial to understand that AMI access can allow AMI users to originate calls and the data exchanged via AMI is often very sensitive and private for your UCM6XXX system. Please be cautious when enabling AMI access on the UCM6XXX and restrict the permission granted to the AMI user. By using AMI on UCM6XXX you agree you understand and acknowledge the risks associated with this.
Creating New AMI User
1. Log in to the UCM6XXX web UI and navigate to Value-added features🡪AMI.
2. Click on “Add”.
3. A new dialog “Create New AMI User” will be prompted.
4. Configure the following parameters in the “Create New AMI User” dialog:
- Username
Configure a name for a new AMI user. The username needs to be at least 8 characters. For example, ucmamiuser1.
- Password
Configure a password for this user to connect to AMI for authentication purposes. The password has the following requirement:
- at least 6 characters
- must contain numeric digit
- at least one lowercase alphabet, or one uppercase alphabet, or one special character
- Privilege
Configure the privilege for the AMI user. Please see the options and definitions in the below table.
- Permitted IP(s)
Configure an IP address Access Control List (ACL) for addresses that should be allowed to authenticate as the AMI user. If not set, all IPs will be denied. The format is IP/subnet. For example, 192.168.40.144/255.255.255.255.
| Privilege Option | Definition |
|---|---|
All | This provides all privilege options to the user. |
Originate | Write-only. It provides permission to originate new calls. |
Call | It provides permission to access information about channels and the ability to configure in a running channel. |
CDR | Read-only. This provides permission to obtain the output of cdr-managerif loaded. |
Agent | This provides permission to access call queue information and agents’ information. It also provides the ability to add members to a call queue. |
CC | Read-only. This provides permission to receive Call Completion events. |
DTMF | Read-only. This provides permission to receive DTMF events. |
Dialplan | Read-only. This provides permission to receive NewExten and VarSet events. |
Reporting | This provides the ability to obtain statistics and status information from the system. |
User Events | This provides permission to send and receive UserEvent. |
Security Events | Read-only. It provides the ability to read security events. |
Special Command | This provides permission to “command” privilege to show information about queue agents, individuals, and all SIP endpoints. |
5. Click on “Save” and then “Apply Changes”.
Now the AMI user is successfully created. After creating the AMI user, it can be edited by clicking on
icon or deleted by clicking on
icon.
Configuring AMI Ports
1. In UCM6XXX web UI🡪Value-added features🡪AMI page, click on “AMI Settings”.
2. A new dialog “AMI Settings” will be prompted.
3. Configure the following parameters in the “AMI Settings” dialog. Users can connect AMI using TCP or
TLS. If using TLS, please set “TLS Enable” to “Yes”.
| Parameter | Definition |
|---|---|
AMI Port | Configures the port number to listen to for AMI connection. The default setting is 7777. |
TLS Enable | Enables listening for AMI connections using TLS. The default setting is No. |
TLS Port | Configures the port to listen to for TLS-based AMI connection. The default setting is 5039. |
Write Timeout | Sets the timeout when writing data to the AMI connection for this user. This option is specified in milliseconds. The default value is 100. |
TLS Bind Address | Configures the address to listen to for TLS-based AMI connections. The default setting is 0.0.0.0, which means all addresses. |
Timestamp Events | Add a Unix epoch timestamp to events. |
TLS Private Key | Upload TLS private key for TLS-based AMI connection. The size of the key file must be under 2 MB. After uploading, the file will be automatically renamed to “ami_private.pem”. |
TLS Cert | Upload the TLS cert for TLS-based AMI connection. It contains private key for the client and signed certificate for the server. The size of the certificate must be under 2MB. After uploading, the file will be automatically renamed to “ami_certificate.pem”. |
4. Click on “Save” and then “Apply Changes” to save the AMI settings.
Establishing Connection and User Authentication
1. To connect AMI using TCP, simply use Telnet to connect to UCM6XXX’s IP address with AMI port.
- If using command line, users can type in:
telnet 192.168.40.144 7777
- If using PuTTY, users might need change the Telnet setting “Telnet Negotiation Mode” to “Passive” first. Then initiate Telnet connection to AMI from Putty.
2. After initiating the connection, users shall see a prompt like below, meaning the connection is established.
Asterisk Call Manager/5.0.0
3. After the connection is established, the system will wait for the user’s input. By default, if there is no input
in 30 seconds, the system will disconnect automatically.
4. To log in and get authenticated, manually enter all the text below:
action: login
username: <ucmamiuser1>
secret: <test123>
Tap on ENTER and users should see a response like below. Sometimes if there is no response after
ENTER, please tap on ENTER again.
Asterisk Call Manager/5.0.0
action: login
username: amitest123
secret: amitest123
Response: Success
Message: Authentication accepted
Event: SuccessfulAuth
Privilege: security,all
EventTV: 2021-10-07T13:56:05.335+0100
Severity: Informational
Service: AMI
EventVersion: 1
AccountID: amitest123
SessionID: 0x7f82e67c48
LocalAddress: IPV4/TCP/0.0.0.0/7777
RemoteAddress: IPV4/TCP/192.168.5.195/64922
UsingPassword: 0
SessionTV: 2021-10-07T13:56:05.335+0100
Users must log in and get authenticated before using other commands.
6. To view all executable AMI commands, enter text below:
action: listcommands
Tap on ENTER. Users will see the following output. (Sometimes if there is no response after ENTER, please tap on ENTER again.)
action: listcommands
Response: Success
AbsoluteTimeout: Set absolute timeout. (Priv: system,call,all)
AcceptCall: (Priv: call,all)
AnalogChanlists: (Priv: <none>)
APILoginTimeSave: (Priv: call,all)
Atxfer: Attended transfer. (Priv: call,all)
BlindTransfer: Blind transfer channel(s) to the given destination (Priv: call,all)
Bridge: Bridge two channels already in the PBX. (Priv: call,all)
BridgeDestroy: Destroy a bridge. (Priv: <none>)
BridgeInfo: Get information about a bridge. (Priv: <none>)
BridgeKick: Kick a channel from a bridge. (Priv: <none>)
BridgeList: Get a list of bridges in the system. (Priv: <none>)
BridgeTechnologyList: List available bridging technologies and their statuses. (Priv: <none>)
BridgeTechnologySuspend: Suspend a bridging technology. (Priv: <none>)
BridgeTechnologyUnsuspend: Unsuspend a bridging technology. (Priv: <none>)
CancelAtxfer: Cancel an attended transfer. (Priv: call,all)
Challenge: Generate Challenge for MD5 Auth. (Priv: <none>)
ChangeMonitor: Change monitoring filename of a channel. (Priv: call,all)
ChannelSync: (Priv: call,all)
Command: Execute Asterisk CLI Command. (Priv: command,specialcommand,all)
ConfbridgeAuthorizeUser: Authorize a user and cache it for be authenticated subsequently. (Priv: call,all)
ConfbridgeImAuthorize: (Priv: call,all)
ConfbridgeKick: Kick a Confbridge user. (Priv: call,all)
ConfbridgeList: List participants in a conference. (Priv: reporting,all)
ConfbridgeListRooms: List active conferences. (Priv: reporting,all)
ConfbridgeLock: Lock a Confbridge conference. (Priv: call,all)
ConfbridgeMute: Mute a Confbridge user. (Priv: call,all)
ConfbridgeRenameUser: Change the name to the special participant. (Priv: call,all)
ConfbridgeReportStatisAndRemoveSchedule: Clean schedule conference list. (Priv: call,all)
ConfbridgeScheduleEnd: Inform the schedule conference information that the schedule conference is end. (Priv: call,all)
ConfbridgeScheduleJoinEarly: Inform the schedule conference information that joined in advance . (Priv: call,all)
ConfbridgeScheduleStart: Inform the schedule conference information. (Priv: call,all)
ConfbridgeScheduleWaitInfoModify: Modify the schedule conference information that joined in advance . (Priv: call,all)
ConfbridgeSetSingleVideoSrc: Set a conference user as the single video source distributed to all other participants. (Priv: call,all)
ConfbridgeSfuAuthorizeUser: Authorize a user and cache it for be authenticated subsequently. (Priv: call,all)
ConfbridgeSfuSwitchVideoQuality: Switch the video quality between 360P and 1080P (Priv: call,all)
ConfbridgeSfuTransferModerator: Transfer the moderator of sfu to the sepecial participant. (Priv: call,all)
ConfbridgeTransferModerator: Transfer the moderator to the special participant. (Priv: call,all)
ConfbridgeUnlock: Unlock a Confbridge conference. (Priv: call,all)
ConfbridgeUnmute: Unmute a Confbridge user. (Priv: call,all)
ConfbridgeUpdateAdminPin: Change the admin pin for a conference. (Priv: call,all)
ControlPlayback: Control the playback of a file being played to a channel. (Priv: call,all)
CoreCheckChannel: (Priv: system,reporting,all)
CoreSettings: Show PBX core settings (version etc). (Priv: system,reporting,all)
CoreShowChannels: List currently active channels. (Priv: system,reporting,all)
CoreStatus: Show PBX core status variables. (Priv: system,reporting,all)
CPUFlowControl: (Priv: call,all)
DAHDIDialOffhook: Dial over DAHDI channel while offhook. (Priv: <none>)
DAHDIDNDoff: Toggle DAHDI channel Do Not Disturb status OFF. (Priv: <none>)
DAHDIDNDon: Toggle DAHDI channel Do Not Disturb status ON. (Priv: <none>)
DAHDIHangup: Hangup DAHDI Channel. (Priv: <none>)
DAHDIRestart: Fully Restart DAHDI channels (terminates calls). (Priv: <none>)
DAHDIShowChannels: Show status of DAHDI channels. (Priv: <none>)
DAHDITransfer: Transfer DAHDI Channel. (Priv: <none>)
DBGet: Get DB Entry. (Priv: system,reporting,all)
DeviceStateList: List the current known device states. (Priv: call,reporting,all)
DiskAlarm: (Priv: call,all)
Events: Control Event Flow. (Priv: <none>)
ExtensionState: Check Extension Status. (Priv: call,reporting,all)
ExtensionStateList: List the current known extension states. (Priv: call,reporting,all)
Filter: Dynamically add filters for the current manager session. (Priv: system,specialcommand,all)
Getvar: Gets a channel variable or function value. (Priv: call,reporting,all)
GSAgents: (Priv: agent,all)
Hangup: Hangup channel. (Priv: system,call,all)
IAXnetstats: Show IAX Netstats. (Priv: system,reporting,all)
IAXpeerlist: List IAX Peers. (Priv: system,reporting,all)
IAXpeers: List IAX peers. (Priv: system,reporting,all)
IAXregistry: Show IAX registrations. (Priv: system,reporting,all)
ListCommands: List available manager commands. (Priv: <none>)
LocalOptimizeAway: Optimize away a local channel when possible. (Priv: system,call,all)
LoggerRotate: Reload and rotate the Asterisk logger. (Priv: system,reporting,all)
Login: Login Manager. (Priv: <none>)
Logoff: Logoff Manager. (Priv: <none>)
MailboxCount: Check Mailbox Message Count. (Priv: call,reporting,all)
MailboxStatus: Check mailbox. (Priv: call,reporting,all)
MixMonitorMute: Mute / unMute a Mixmonitor recording. (Priv: system,call,all)
Monitor: Monitor a channel. (Priv: call,all)
NWayRedirect: (Priv: call,all)
Originate: Originate a call. (Priv: originate,all)
Park: Park a channel. (Priv: call,all)
ParkedCalls: List parked calls. (Priv: call,all)
Parkinglots: Get a list of parking lots (Priv: call,all)
PauseCall: (Priv: <none>)
PauseMonitor: Pause monitoring of a channel. (Priv: call,all)
Ping: Keepalive command. (Priv: <none>)
PJSIPQualify: Qualify a chan_pjsip endpoint. (Priv: system,reporting,all)
PJSIPRegister: Register an outbound registration. (Priv: system,reporting,all)
PJSIPShowRegistrationsOutbound: Lists PJSIP outbound registrations. (Priv: system,reporting,all)
PJSIPUnregister: Unregister an outbound registration. (Priv: system,reporting,all)
PlayDTMF: Play DTMF signal on a specific channel. (Priv: call,all)
PresenceState: Check Presence State (Priv: call,reporting,all)
PresenceStateList: List the current known presence states. (Priv: call,reporting,all)
PRIDebugFileUnset: Disables file output for PRI debug messages (Priv: <none>)
PRIDebugSet: Set PRI debug levels for a span (Priv: <none>)
PRIShowSpans: Show status of PRI spans. (Priv: <none>)
QueueAdd: Add interface to queue. (Priv: agent,all)
QueueChangePriorityCaller: Change priority of a caller on queue. (Priv: <none>)
QueueClean: Clean up the seat status of the queue (Priv: <none>)
QueueLog: Adds custom entry in queue_log. (Priv: agent,all)
QueueLogin: (Priv: agent,all)
QueueLogoff: (Priv: agent,all)
QueueMemberRingInUse: Set the ringinuse value for a queue member. (Priv: agent,all)
QueuePause: Makes a queue member temporarily unavailable. (Priv: agent,all)
QueuePenalty: Set the penalty for a queue member. (Priv: agent,all)
QueueReload: Reload a queue, queues, or any sub-section of a queue or queues. (Priv: <none>)
QueueRemove: Remove interface from queue. (Priv: agent,all)
QueueReset: Reset queue statistics. (Priv: <none>)
QueueRule: Queue Rules. (Priv: <none>)
Queues: Queues. (Priv: <none>)
QueueStatus: Show queue status. (Priv: <none>)
QueueSummary: Show queue summary. (Priv: <none>)
Redirect: Redirect (transfer) a call. (Priv: call,all)
SendText: Send text message to channel. (Priv: call,all)
Setvar: Sets a channel variable or function value. (Priv: call,all)
ShowDialPlan: Show dialplan contexts and extensions (Priv: config,reporting,all)
Status: List channel status. (Priv: system,call,reporting,all)
StopMixMonitor: Stop recording a call through MixMonitor, and free the recording's file handle. (Priv: system,call,all)
StopMonitor: Stop monitoring a channel. (Priv: call,all)
UnpauseMonitor: Unpause monitoring of a channel. (Priv: call,all)
UserEvent: Send an arbitrary event. (Priv: user,all)
VoicemailForward: VoicemailForward (Priv: command,user,all)
VoicemailRecount: VoicemailRecount (Priv: command,user,all)
VoicemailRefresh: Tell Asterisk to poll mailboxes for a change (Priv: user,all)
VoicemailUsersList: List All Voicemail User Information. (Priv: call,reporting,all)
VoicemailUserStatus: Show the status of given voicemail user's info. (Priv: call,reporting,all)
WaitEvent: Wait for an event to occur. (Priv: <none>)
Only some of the commands are supported.
Examples
There are mainly 3 types of AMI packets:
- Action: packets sent by client to Asterisk to request to perform a particular action. There are a limited number of actions for the client to use and each of them is decided by the module in Asterisk server. Only one action can be performed each time and the action packet contains the action name and parameters.
- Response: response by Asterisk to the client action.
- Event: information about the events of Asterisk core or expansion modules.
Please make sure the AMI user is logged in and authenticated first.
Example 1: Originate an internal call
action: originate
channel: PJSIP/1000
context: from-internal
exten: 1001
priority: 1
timeout: 60000
Example 2: Originate an external call via trunk
action: originate
channel: PJSIP/1000
context: outbound-allroutes
exten: 123456
priority: 1
timeout: 60000
Example 3: Channel hang-up
This command will hang up active call.
action: Hangup
channel: PJSIP/trunk_2-000000
Channel – The channel name to be hangup.
Example 4: Query the status of queue
action: queues
Response: Success
EventList: start
Message: Queues list will follow
Event: QueueStatus
Queue: 6500
CallsTotal: 0
CallCount: 0
CallsComplete: 0
CallsAbandoned: 0
Strategy: ringall
Chairman:
EnableAgentLogin: no
QueueName: tt
SeviceLevel: SL:0.0% within 0s
AbandonedRate: 0.00%
AvgWaitTime: 0
AvgTalkTime: 0
AvailableCount: 0
AgentCount: 1
Event: QueueMemberStatus
Queue: 6500
Location: PJSIP/1000
MemberName: PJSIP/1000
Membership: dynamic
Penalty: 0
CallsTaken: 0
LastCall: 0
Status: 5
EnableAgentLogin: no
LoginTime: 1633618142
CallsAbandon: 0
TalkTime: 0
CallerChannel:
PausedTime: 0
Paused: 0
Event: QueuesComplete
EventList: Complete
ListItems: 1
Example 5: Query the status of agents in queues
action: GSAgents
Response: Success
EventList: start
Message: Agents status will follow
Event: GsAgent
Agent: PJSIP/1000
QueueName: tt
Queue: 6500
Location: PJSIP/1000
Membership: dynamic
Penalty: 0
CallsTaken: 0
LastCall: 0
Status: 5
LoginTime: 1633618142
CallsAbandon: 0
TalkTime: 0
CallerChannel:
Paused: 0
Event: GsAgentComplete
EventList: Complete
ListItems: 1
* Asterisk is a Registered Trademark of Digium, Inc.
