275 lines
12 KiB
TeX
275 lines
12 KiB
TeX
\section{The Asterisk Manager TCP/IP API}
|
|
|
|
The manager is a client/server model over TCP. With the manager interface,
|
|
you'll be able to control the PBX, originate calls, check mailbox status,
|
|
monitor channels and queues as well as execute Asterisk commands.
|
|
|
|
AMI is the standard management interface into your Asterisk server.
|
|
You configure AMI in manager.conf. By default, AMI is available on
|
|
TCP port 5038 if you enable it in manager.conf.
|
|
|
|
AMI receive commands, called "actions". These generate a "response"
|
|
from Asterisk. Asterisk will also send "Events" containing various
|
|
information messages about changes within Asterisk. Some actions
|
|
generate an initial response and data in the form list of events.
|
|
This format is created to make sure that extensive reports do not
|
|
block the manager interface fully.
|
|
|
|
Management users are configured in the configuration file manager.conf and are
|
|
given permissions for read and write, where write represents their ability
|
|
to perform this class of "action", and read represents their ability to
|
|
receive this class of "event".
|
|
|
|
If you develop AMI applications, treat the headers
|
|
in Actions, Events and Responses as local to that particular
|
|
message. There is no cross-message standardization of headers.
|
|
|
|
If you develop applications, please try to reuse existing manager
|
|
headers and their interpretation. If you are unsure, discuss on
|
|
the asterisk-dev mailing list.
|
|
|
|
Manager subscribes to extension status reports from all channels,
|
|
to be able to generate events when an extension or device changes
|
|
state. The level of details in these events may depend on the channel
|
|
and device configuration. Please check each channel configuration
|
|
file for more information. (in sip.conf, check the section on
|
|
subscriptions and call limits)
|
|
|
|
|
|
\section{Command Syntax}
|
|
|
|
Management communication consists of tags of the form "header: value",
|
|
terminated with an empty newline (\textbackslash r\textbackslash n) in
|
|
the style of SMTP, HTTP, and other headers.
|
|
|
|
The first tag MUST be one of the following:
|
|
|
|
\begin{itemize}
|
|
\item Action: An action requested by the CLIENT to the Asterisk SERVER.
|
|
Only one "Action" may be outstanding at any time.
|
|
\item Response: A response to an action from the Asterisk SERVER to the CLIENT.
|
|
\item Event: An event reported by the Asterisk SERVER to the CLIENT
|
|
\end{itemize}
|
|
|
|
\section{Manager commands}
|
|
|
|
To see all of the available manager commands, use the "manager show commands"
|
|
CLI command.
|
|
|
|
You can get more information about a manager command
|
|
with the "manager show command $<$command$>$" CLI command in Asterisk.
|
|
|
|
\section{Examples}
|
|
|
|
Login - Log a user into the manager interface.
|
|
|
|
\begin{verbatim}
|
|
Action: Login
|
|
Username: testuser
|
|
Secret: testsecret
|
|
\end{verbatim}
|
|
|
|
Originate - Originate a call from a channel to an extension.
|
|
|
|
\begin{verbatim}
|
|
Action: Originate
|
|
Channel: sip/12345
|
|
Exten: 1234
|
|
Context: default
|
|
\end{verbatim}
|
|
|
|
Originate - Originate a call from a channel to an extension without waiting
|
|
for call to complete.
|
|
|
|
\begin{verbatim}
|
|
Action: Originate
|
|
Channel: sip/12345
|
|
Exten: 1234
|
|
Context: default
|
|
Async: yes
|
|
\end{verbatim}
|
|
|
|
Redirect with ExtraChannel:
|
|
|
|
Attempted goal:
|
|
Have a 'robot' program Redirect both ends of an already-connected call
|
|
to a meetme room using the ExtraChannel feature through the management interface.
|
|
|
|
\begin{verbatim}
|
|
Action: Redirect
|
|
Channel: DAHDI/1-1
|
|
ExtraChannel: SIP/3064-7e00 (varies)
|
|
Exten: 680
|
|
Priority: 1
|
|
\end{verbatim}
|
|
|
|
Where 680 is an extension that sends you to a MeetMe room.
|
|
|
|
There are a number of GUI tools that use the manager interface, please search
|
|
the mailing list archives and the documentation page on the
|
|
\url{http://www.asterisk.org} web site for more information.
|
|
|
|
\section{Ensuring all modules are loaded}
|
|
It is possible to connect to the manager interface before all Asterisk modules
|
|
are loaded. To ensure that an application does not send AMI actions that might
|
|
require a module that has not yet loaded, the application can listen for the
|
|
FullyBooted manager event. It will be sent upon connection if all modules have
|
|
been loaded, or as soon as loading is complete. The event:
|
|
|
|
\begin{verbatim}
|
|
Event: FullyBooted
|
|
Privilege: system,all
|
|
Status: Fully Booted
|
|
\end{verbatim}
|
|
|
|
\section{Device status reports}
|
|
|
|
|
|
\section{Some standard AMI headers}
|
|
\begin{verbatim}
|
|
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)
|
|
\end{verbatim}
|
|
|
|
** Please try to re-use existing headers to simplify manager message parsing in clients.
|
|
|
|
Read the CODING-GUIDELINES if you develop new manager commands or events.
|