Introduction

The Asterisk Manager Interface (AMI) is a monitoring and management interface over TCP. With the manager interface, you can control the UCx to: originate calls, check mailbox status, monitor channels, queues and also execute commands.

Protocol Overview

The protocol has the following characteristics:

1. By default, AMI is available on TCP port 5038.
2. AMI is a plain text protocol and AMI messages (regardless of message type) are encoded in the same way.
3. Management communication consists of tags of the form "HEADER: VALUE", terminated with <CR><LF>.
4. The end of message is indicated by a blank line (i.e. two <CR>/<LF> in a row).
5. Before issuing commands to UCx, you must establish a manager session, i.e. login and authenticate as a user. See Asterisk API page on how to create a manager user.
6. When a message is sent from client to UCx, the first line of the message should have the "Action" header.
7. When a message is sent from UCx to the client, the first line of the message will have either "Event" or "Response" header.
8. The order of lines within a message is insignificant.

Some Standard AMI Headers

• Account: – Account Code (Status)
• AccountCode: – Account Code (cdr_manager)
• ACL: <Y | N> – Does ACL exist for object ?
• Action: <action> – Request or notification of a particular action
• Address-IP: – IPaddress
• Address-Port: – IP port number
• Agent: <string> – Agent name
• AMAflags: – AMA flag (cdr_manager, sippeers)
• AnswerTime: – Time of answer (cdr_manager)
• Append: <bool> – CDR userfield Append flag
• Application: – Application to use
• Async: – Whether or not to use fast setup
• AuthType: – Authentication type (for login or challenge) "md5"
• BillableSeconds: – Billable seconds for call (cdr_manager)
• CallerID: – Caller id (name and number in Originate & cdr_manager)
• CallerID: – CallerID number Number or "<unknown>" or "unknown" (should change to "<unknown>" in app_queue)
• CallerID1: – Channel 1 CallerID (Link event)
• CallerID2: – Channel 2 CallerID (Link event)
• CallerIDName: – CallerID name Name or "<unknown>" or "unknown" (should change to "<unknown>" in app_queue)
• Callgroup: – Call group for peer/user
• CallsTaken: <num> – Queue status variable
• Cause: <value> – Event change cause - "Expired"
• Cause: <value> – Hangupcause (channel.c)
• CID-CallingPres: – Caller ID calling presentation
• Channel: <channel> – Channel specifier
• Channel: <dialstring> – Dialstring in Originate
• Channel: <tech/[peer/username]> – Channel in Registry events (SIP, IAX2)
• Channel: <tech> – Technology (SIP/IAX2 etc) in Registry events
• ChannelType: – Tech: SIP, IAX2, DAHDI, MGCP etc
• Channel1: – Link channel 1
• Channel2: – Link channel 2
• ChanObjectType: – "peer", "user"
• Codecs: – Codec list
• CodecOrder: – Codec order, separated with comma ","
• Command: – Cli command to run
• Context: – Context
• Count: <num> – Number of callers in queue
• Data: – Application data
• Default-addr-IP: – IP address to use before registration
• Default-Username: – Username part of URI to use before registration
• Destination: – Destination for call (Dialstring ) (dial, cdr_manager)
• DestinationContext: – Destination context (cdr_manager)
• DestinationChannel: – Destination channel (cdr_manager)
• DestUniqueID: – UniqueID of destination (dial event)
• Direction: <type> – Audio to mute (read | write | both)
• Disposition: – Call disposition (CDR manager)
• Domain: <domain> – DNS domain
• Duration: <secs> – Duration of call (cdr_manager)
• Dynamic: <Y | N> – Device registration supported?
• Endtime: – End time stamp of call (cdr_manager)
• EventList: <flag> – Flag being "Start", "End", "Cancelled" or "ListObject"
• Events: <eventmask> – Eventmask filter ("on", "off", "system", "call", "log")
• Exten: – Extension (Redirect command)
• Extension: – Extension (Status)
• Family: <string> – ASTdb key family
• File: <filename> – Filename (monitor)
• Format: <format> – Format of sound file (monitor)
• From: <time> – Parking time (ParkedCall event)
• Hint: – Extension hint
• Incominglimit: – SIP Peer incoming limit
• Key: Key: – ASTdb Database key
• LastApplication: – Last application executed (cdr_manager)
• LastCall: <num> – Last call in queue
• LastData: – Data for last application (cdr_manager)
• Link: – (Status)
• ListItems: <number> – Number of items in Eventlist (Optionally sent in "end" packet)
• Location: – Interface (whatever that is -maybe tech/name in app_queue )
• Loginchan: – Login channel for agent
• Logintime: <number> – Login time for agent
• Mailbox: – VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
• MD5SecretExist: <Y | N> – Whether secret exists in MD5 format
• Membership: <string> – "Dynamic" or "static" member in queue
• Message: <text> – Text message in ACKs, errors (explanation)
• Mix: <bool> – Boolean parameter (monitor)
• MOHSuggest: – Suggested music on hold class for peer (mohsuggest)
• NewMessages: <count> – Count of new Mailbox messages (mailboxcount)
• Newname:
• ObjectName: – Name of object in list
• OldName: – Something in Rename (channel.c)
• OldMessages: <count> – Count of old mailbox messages (mailboxcount)
• Outgoinglimit: – SIP Peer outgoing limit
• Paused: <num> – Queue member paused status
• Peer: <tech/name> – "channel" specifier
• PeerStatus: <tech/name> – Peer status code "Unregistered", "Registered", "Lagged", "Reachable"
• Penalty: <num> – Queue penalty
• Priority: – Extension priority
• Privilege: <privilege> – AMI authorization class (system, call, log, verbose, command, agent, user)
• Pickupgroup: – Pickup group for peer
• Position: <num> – Position in Queue
• Queue: – Queue name
• Reason: – "Autologoff"
• Reason: – "Chanunavail"
• Response: <response> – response code, like "200 OK" "Success", "Error", "Follows"
• Restart: – "True", "False"
• RegExpire: – SIP registry expire
• RegExpiry: – SIP registry expiry
• Reason: – Originate reason code
• Seconds: – Seconds (Status)
• Secret: <password> – Authentication secret (for login)
• SecretExist: <Y | N> – Whether secret exists
• Shutdown: – "Uncleanly", "Cleanly"
• SIP-AuthInsecure:
• SIP-FromDomain: – Peer FromDomain
• SIP-FromUser: – Peer FromUser
• SIP-NatSupport:
• SIPLastMsg:
• Source: – Source of call (dial event, cdr_manager)
• SrcUniqueID: – UniqueID of source (dial event)
• StartTime: – Start time of call (cdr_manager)
• State: – Channel state
• State: <1 | 0> – Mute flag
• Status: – Registration status (Registry events SIP)
• Status: – Extension status (Extensionstate)
• Status: – Peer status (if monitored) ** Will change name ** "unknown", "lagged", "ok"
• Status: <num> – Queue Status
• Status: – DND status (DNDState)
• Time: <sec> – Roundtrip time (latency)
• Timeout: – Parking timeout time
• Timeout: – Timeout for call setup (Originate)
• Timeout: <seconds> – Timeout for call
• Uniqueid: – Channel Unique ID
• Uniqueid1: – Channel 1 Unique ID (Link event)
• Uniqueid2: – Channel 2 Unique ID (Link event)
• User: – Username (SIP registry)
• UserField: – CDR userfield (cdr_manager)
• Val: – Value to set/read in ASTdb
• Variable: – Variable AND value to set (multiple separated with | in Originate)
• Variable: <name> – For channel variables
• Value: <value> – Value to set
• VoiceMailbox: – VM Mailbox in SIPpeers
• Waiting: – Count of mailbox messages (mailboxstatus)

Message Types

There are 3 types of messages on the AMI:

• Actions: Only the client can generate Actions and only one Action may be outstanding at any time.
• Responses: Actions have at least one Response, indicating the result of the executed (or requested) action.
• Events: There are two kind of events. The ones attached to a particular response for a particular action, and the ones that asterisk generate to inform the connected client about things that are happening in the server (like call events, changes in variables values, agents and other clients that connect/disconnect to/from the server, etc).

Manager events

Manager events are one-way messages sent from UCx to AMI clients to report something that has occurred on the system. When connected to the native TCP interface for the AMI, manager events are delivered asynchronously.

For details on events, see Asterisk 11 AMI Events.

• AgentCalled
• AgentCompletePage
• AgentConnectPage
• AgentDumpPage
• Agentlogin
• Agentlogoff
• AgentRingNoAnswer
• Alarm
• AlarmClearP
• Bridge
• BridgeAction
• BridgeExec
• ChanSpyStart
• ChanSpyStop
• ConfbridgeEnd
• ConfbridgeJoin
• ConfbridgeLeave
• ConfbridgeStartP
• ConfbridgeTalking
• DAHDIChannelP
• DialP
• DNDState
• DTMF
• ExtensionStatus
• FullyBootedPa
• Hangup
• HangupHandlerPop
• HangupHandlerPush
• HangupHandlerRun
• HangupRequest
• Hold
• Join
• Leave
• LocalBridge
• LogChannel
• Masquerade
• MeetmeEnd
• MeetmeJoin
• MeetmeLeave
• MeetmeMute
• MeetmeTalking
• MeetmeTalkRequestP
• MessageWaiting
• ModuleLoadReport
• NewAccountCode
• NewCallerid
• Newchannel
• Newexten
• NewPeerAccount
• Newstate
• OriginateResponse
• ParkedCall
• ParkedCallGiveUp
• ParkedCallTimeOut
• Pickup
• PresenceStatus
• QueueCallerAbandon
• QueueMemberAddedP
• QueueMemberPaused
• QueueMemberPenalty
• QueueMemberRemoved
• QueueMemberRinginuse
• QueueMemberStatus
• Rename
• Shutdown
• SoftHangupRequest
• SpanAlarm
• SpanAlarmClearP
• UnParkedCallP
• UserEvent
• VarSet

Manager actions

Manager actions are requests from a client that have associated responses that come back from UCx. That is, a manager action may be a request that UCx perform some action and return the result. For example, you can have an AMI action to originate a call or an AMI action requesting for data. For details on the actions, see Asterisk 11 AMI Actions.

To view a list of manager actions, navigate to PBX > Tools > Asterisk CLI and enter the command: manager show commands.
You can get more information about a manager command with: manager show command <commandname> .

Examples

Login - log a user into the manager interface.

Originate - originate a call from a channel to an extension.

MailboxCount - query the number of messages in a mailbox