mirror of
https://github.com/asterisk/asterisk.git
synced 2026-04-27 17:23:10 +00:00
7e9a71f5d8
https://origsvn.digium.com/svn/asterisk/trunk ........ r265320 | twilson | 2010-05-24 14:06:40 -0500 (Mon, 24 May 2010) | 14 lines Add the FullyBooted AMI event 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: Event: FullyBooted Privilege: system,all Status: Fully Booted Review: https://reviewboard.asterisk.org/r/639/ ........ r265467 | twilson | 2010-05-24 17:21:58 -0500 (Mon, 24 May 2010) | 1 line Merge the rest of the FullyBooted patch ........ git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/1.4@265570 65c4cc65-6c06-0410-ace0-fbb531ad65f3
329 lines
12 KiB
Plaintext
329 lines
12 KiB
Plaintext
The Asterisk Manager TCP/IP API - AMI
|
|
=====================================
|
|
|
|
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".
|
|
|
|
The Asterisk manager interface in version 1.0.x of Asterisk is
|
|
not very well standardized. Work is under way to change this
|
|
to Asterisk 1.2. 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.
|
|
|
|
Device status reports
|
|
---------------------
|
|
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)
|
|
|
|
|
|
Command Syntax
|
|
--------------
|
|
Management communication consists of tags of the form "header: value",
|
|
terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and
|
|
other headers.
|
|
|
|
|
|
The first tag MUST be one of the following:
|
|
|
|
* Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
|
|
* Response: A response to an action from the Asterisk SERVER to the CLIENT.
|
|
* Event: An event reported by the Asterisk SERVER to the CLIENT
|
|
|
|
|
|
Manager commands
|
|
----------------
|
|
Output from the CLI command 'show manager' command:
|
|
|
|
* Ping: Ping
|
|
* Logoff: Logoff Manager
|
|
* Hangup: Hangup Channel
|
|
* Status: Status
|
|
* Redirect: Redirect
|
|
* Originate: Originate Call
|
|
* MailboxStatus: Check Mailbox
|
|
* Command: Execute Command
|
|
* ExtensionState: Check Extension Status
|
|
* AbsoluteTimeout: Set Absolute Timeout
|
|
* MailboxCount: Check Mailbox Message Count
|
|
* Monitor: Monitor a channel
|
|
* StopMonitor: Stop monitoring a channel
|
|
* ChangeMonitor: Change monitoring filename of a channel
|
|
* IAXpeers: List IAX Peers (Defaults to IAX2)
|
|
* SIPpeers: List SIP peers
|
|
* SIPshowpeer: Show data about one SIP peer
|
|
* Queues: Queues
|
|
* QueueStatus: Queue Status
|
|
|
|
This list depends on the version of Asterisk you are using, as
|
|
well as which modules that are loaded.
|
|
|
|
Command Summary
|
|
--------------
|
|
|
|
Command: Command
|
|
Parameters: Command
|
|
|
|
Command: ExtensionState
|
|
Parameters: Exten, Context, ActionID
|
|
|
|
Command: Hangup
|
|
Parameters: Channel
|
|
|
|
Command: Logoff
|
|
Parameters: None
|
|
|
|
Command: MailboxCount
|
|
Parameters: Mailbox, ActionID
|
|
|
|
Command: MailboxStatus
|
|
Parameters: Mailbox, ActionID
|
|
|
|
Command: Originate
|
|
Parameters: Channel, Exten, Context, Priority, Timeout,
|
|
CallerID, Variable, Account, Application, Data, Async
|
|
|
|
Command: Ping
|
|
Parameters: None
|
|
|
|
Command: PlayDTMF
|
|
Parameters: Channel, Digit
|
|
|
|
Command: Redirect
|
|
Parameters: Channel, ExtraChannel, Exten, Context, Priority
|
|
|
|
Command: Timeout
|
|
Parameters: Channel, Timeout
|
|
|
|
You can always get more information about a manager command
|
|
with the "show manager command <command>" CLI command in Asterisk.
|
|
|
|
Determining when all modules have finished loading
|
|
--------------------------------------------------
|
|
It is handy to have a single event notification for when all Asterisk
|
|
modules have been loaded--especially for situations like running
|
|
automated tests. This event will fire 1) immediately upon all modules
|
|
loading or 2) upon connection to the AMI interface if the modules have
|
|
already finished loading before the connection was made. This ensures
|
|
that a user will never miss getting a FullyBooted event. In vary rare
|
|
circumstances, it might be possible to get two copies of the message
|
|
if the AMI connection is made right as the modules finish loading.
|
|
|
|
Example:
|
|
Event: FullyBooted
|
|
Privilege: system,all
|
|
Status: Fully Booted
|
|
|
|
|
|
Examples
|
|
--------
|
|
Login - Log a user into the manager interface.
|
|
|
|
Action: Login
|
|
Username: testuser
|
|
Secret: testsecret
|
|
|
|
Originate - Originate a call from a channel to an extension.
|
|
|
|
Action: Originate
|
|
Channel: sip/12345
|
|
Exten: 1234
|
|
Context: default
|
|
|
|
Originate - Originate a call from a channel to an extension without waiting
|
|
for call to complete.
|
|
|
|
Action: Originate
|
|
Channel: sip/12345
|
|
Exten: 1234
|
|
Context: default
|
|
Async: yes
|
|
|
|
|
|
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.
|
|
|
|
Action: Redirect
|
|
Channel: Zap/1-1
|
|
ExtraChannel: SIP/3064-7e00 (varies)
|
|
Exten: 680
|
|
Priority: 1
|
|
|
|
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
|
|
http://www.asterisk.org web site for more information.
|
|
|
|
|
|
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, ZAP, 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)
|
|
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)
|
|
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
|
|
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)
|
|
|
|
** 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.
|