AMI (Asterisk Management Interface)

  • Updated on September 15, 2023

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:

https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=4817239

The UCM6XXX provides restricted AMI access for users. In order to connect to Asterisk Manager Interface on UCM6XXX, please follow the steps below.

  1. Create new AMI user.
  2. Configure AMI ports for connection.
  3. 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”.

Figure 1: Web UI🡪Internal Options🡪AMI

3. A new dialog “Create New AMI User” will be prompted.

Figure 2: Create New AMI User Dialog

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 OptionDefinition

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-manager

if 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.

Table 1: AMI User Privilege

5. Click on “Save” and then “Apply Changes”.

Figure 3: AMI User Created

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”.

Figure 4: AMI Settings

2. A new dialog “AMI Settings” will be prompted.

Figure 5: AMI Settings Dialog

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”.

ParameterDefinition

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”.

Table 2: AMI Settings Parameters

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.
Figure 6: Telnet Settings in PuTTY

Figure 7: Telnet Connection Using 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.

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment