Grandstream Networks, Inc.

UCM6XXX series
Asterisk Manager Interface (AMI) Guide
 Table of Contents
INTRODUCTION ............................................................................................................. 3

CREATING NEW AMI USER .......................................................................................... 4

CONFIGURING AMI PORTS .......................................................................................... 6

ESTABLISHING CONNECTION AND USER AUTHENTICATION ................................. 8

EXAMPLES .................................................................................................................. 14

Table of Figures
Figure 1: Web UIInternal OptionsAMI .................................................................................................... 4
Figure 2: Create New AMI User Dialog ......................................................................................................... 4
Figure 3: AMI User Created .......................................................................................................................... 5
Figure 4: AMI Settings ................................................................................................................................... 6
Figure 5: AMI Settings Dialog ....................................................................................................................... 6
Figure 6: Telnet Settings in PuTTY ............................................................................................................... 8
Figure 7: Telnet Connection Using PuTTY .................................................................................................... 9
Figure 8: Telnet Connection to AMI Using TCP ............................................................................................ 9
Figure 9: User Authentication Successful ................................................................................................... 10
Figure 10: AMI Command Example ............................................................................................................ 13
Figure 11: Example 1 - Originate Internal Call Ext 1000 to Ext 1001 ......................................................... 14
Figure 12: Example 2 - Originate External Call........................................................................................... 14
Figure 13: Example 3 - Channel Hangup .................................................................................................... 14
Figure 14: Example 4 - Queue Status ......................................................................................................... 15
Figure 15: Example 5 - GSAgents Command............................................................................................. 16

Table of Tables
Table 1: AMI User Privilege ........................................................................................................................... 5
Table 2: AMI Settings Parameters ................................................................................................................. 7

Page | 2
UCM6XXX Asterisk Manager Interface (AMI) Guide
INTRODUCTION

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.

Note: UCM6XXX series include UCM62xx series, UCM630x/A series and UCM6510.

Warning:
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 user 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.

Page | 3
UCM6XXX Asterisk Manager Interface (AMI) Guide
CREATING NEW AMI USER

1. Log in 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 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 purpose. 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

Page | 4
UCM6XXX Asterisk Manager Interface (AMI) Guide
  Privilege
Configure the privilege for the AMI user. Please see options and definitions in 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.

Table 1: AMI User Privilege

Privilege Option Definition

All This provides all privilege options to user.

Originate Write-only. It provides permission to originate new calls.

It provides permission to access information about channels and ability to configure in
Call
a running channel.
CDR Read-only. This provides permission to obtain output of cdr-manager, if loaded.
This provides permission to access call queue information and agents’ information. It
Agent
also provides 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 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 ability to read security events.

This provides permission to “command” privilege to show information about queue

Special Command
agents, individual and all SIP endpoints.

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

Figure 3: AMI User Created

Page | 5
UCM6XXX Asterisk Manager Interface (AMI) Guide
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 “AMI Settings” dialog. Users can connect AMI using TCP or
TLS. If using TLS, please set “TLS Enable” to “Yes”.

Page | 6
UCM6XXX Asterisk Manager Interface (AMI) Guide
 Table 2: AMI Settings Parameters

Parameter Definition

Configures the port number to listen to for AMI connection.

AMI Port
The default setting is 7777.
Enables listening for AMI connections using TLS.
TLS Enable
The default setting is No.
Configures the port to listen to for TLS-based AMI connection.
TLS Port
The default setting is 5039.
Sets the timeout when writing data to the AMI connection for this user. This option
Write Timeout
is specified in milliseconds. The default value is 100.
Configures the address to listen to for TLS-based AMI connections.
TLS Bind Address
The default setting is 0.0.0.0, which means all addresses.

Timestamp Events Add a Unix epoch timestamp to events.

Upload TLS private key for TLS-based AMI connection. The size of the key file must
TLS Private Key be under 2 MB. After uploading, the file will be automatically renamed to
“ami_private.pem”.
Upload the TLS cert for TLS-based AMI connection. It contains private key for the
TLS Cert 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.

Page | 7
UCM6XXX Asterisk Manager Interface (AMI) Guide
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

Page | 8
UCM6XXX Asterisk Manager Interface (AMI) Guide
 Figure 7: Telnet Connection Using PuTTY

2. After initiating connection, users shall see prompt like below, meaning connection is established.

Asterisk Call Manager/5.0.0

Figure 8: Telnet Connection to AMI Using TCP

3. After the connection is established, the system will wait for 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 response like below. Sometimes if there is no response after
ENTER, please tap on ENTER again.

Page | 9
UCM6XXX Asterisk Manager Interface (AMI) Guide
 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

Figure 9: User Authentication Successful

Note: 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>)

P a g e | 10
UCM6XXX Asterisk Manager Interface (AMI) Guide
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)

P a g e | 11
UCM6XXX Asterisk Manager Interface (AMI) Guide
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>)

P a g e | 12
UCM6XXX Asterisk Manager Interface (AMI) Guide
 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>)

Figure 10: AMI Command Example

Note: Only some of the commands are supported.

P a g e | 13
UCM6XXX Asterisk Manager Interface (AMI) Guide
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.

Note: 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

Figure 11: Example 1 - Originate Internal Call Ext 1000 to Ext 1001

Example 2: Originate an external call via trunk

action: originate
channel: PJSIP/1000
context: outbound-allroutes
exten: 123456
priority: 1
timeout: 60000

Figure 12: Example 2 - Originate External Call

Example 3: Channel hang-up

Note: This command will hang up active call.

action: Hangup
channel: PJSIP/trunk_2-000000

Figure 13: Example 3 - Channel Hangup

Channel - The channel name to be hangup.

P a g e | 14
UCM6XXX Asterisk Manager Interface (AMI) Guide
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

Figure 14: Example 4 - Queue Status

P a g e | 15
UCM6XXX Asterisk Manager Interface (AMI) Guide
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

Figure 15: Example 5 - GSAgents Command

* Asterisk is a Registered Trademark of Digium, Inc.

P a g e | 16
UCM6XXX Asterisk Manager Interface (AMI) Guide