Add the FullyBooted AMI event
[asterisk/asterisk.git] / doc / tex / manager.tex
1 \section{The Asterisk Manager TCP/IP API}
2
3 The manager is a client/server model over TCP. With the manager interface,
4 you'll be able to control the PBX, originate calls, check mailbox status,
5 monitor channels and queues as well as execute Asterisk commands.
6
7 AMI is the standard management interface into your Asterisk server.
8 You configure AMI in manager.conf. By default, AMI is available on
9 TCP port 5038 if you enable it in manager.conf.
10
11 AMI receive commands, called "actions". These generate a "response"
12 from Asterisk. Asterisk will also send "Events" containing various
13 information messages about changes within Asterisk. Some actions
14 generate an initial response and data in the form list of events.
15 This format is created to make sure that extensive reports do not
16 block the manager interface fully.
17
18 Management users are configured in the configuration file manager.conf and are
19 given permissions for read and write, where write represents their ability
20 to perform this class of "action", and read represents their ability to
21 receive this class of "event".
22
23 If you develop AMI applications, treat the headers
24 in Actions, Events and Responses as local to that particular
25 message. There is no cross-message standardization of headers.
26
27 If you develop applications, please try to reuse existing manager
28 headers and their interpretation. If you are unsure, discuss on
29 the asterisk-dev mailing list.
30
31 Manager subscribes to extension status reports from all channels,
32 to be able to generate events when an extension or device changes
33 state. The level of details in these events may depend on the channel
34 and device configuration. Please check each channel configuration
35 file for more information. (in sip.conf, check the section on
36 subscriptions and call limits)
37
38
39 \section{Command Syntax}
40
41 Management communication consists of tags of the form "header: value",
42 terminated with an empty newline (\textbackslash r\textbackslash n) in 
43 the style of SMTP, HTTP, and other headers.
44
45 The first tag MUST be one of the following:
46
47 \begin{itemize}
48     \item Action: An action requested by the CLIENT to the Asterisk SERVER. 
49         Only one "Action" may be outstanding at any time.
50     \item Response: A response to an action from the Asterisk SERVER to the CLIENT.
51     \item Event: An event reported by the Asterisk SERVER to the CLIENT
52 \end{itemize}
53
54 \section{Manager commands}
55
56 To see all of the available manager commands, use the "manager show commands"
57 CLI command.
58
59 You can get more information about a manager command
60 with the "manager show command $<$command$>$" CLI command in Asterisk.
61
62 \section{Examples}
63
64 Login - Log a user into the manager interface.
65
66 \begin{verbatim}
67    Action: Login
68    Username: testuser
69    Secret: testsecret
70 \end{verbatim}
71
72 Originate - Originate a call from a channel to an extension.
73
74 \begin{verbatim}
75    Action: Originate
76    Channel: sip/12345
77    Exten: 1234
78    Context: default
79 \end{verbatim}
80
81 Originate - Originate a call from a channel to an extension without waiting
82 for call to complete.
83
84 \begin{verbatim}
85    Action: Originate
86    Channel: sip/12345
87    Exten: 1234
88    Context: default
89    Async: yes
90 \end{verbatim}
91
92 Redirect with ExtraChannel:
93
94   Attempted goal:
95   Have a 'robot' program Redirect both ends of an already-connected call
96   to a meetme room using the ExtraChannel feature through the management interface.
97
98 \begin{verbatim}
99   Action: Redirect
100   Channel: DAHDI/1-1
101   ExtraChannel: SIP/3064-7e00 (varies)
102   Exten: 680
103   Priority: 1
104 \end{verbatim}
105
106 Where 680 is an extension that sends you to a MeetMe room.
107
108 There are a number of GUI tools that use the manager interface, please search
109 the mailing list archives and the documentation page on the
110 \url{http://www.asterisk.org} web site for more information.
111
112 \section{Ensuring all modules are loaded}
113 It is possible to connect to the manager interface before all Asterisk modules
114 are loaded. To ensure that an application does not send AMI actions that might
115 require a module that has not yet loaded, the application can listen for the
116 FullyBooted manager event. It will be sent upon connection if all modules have
117 been loaded, or as soon as loading is complete. The event:
118
119 \begin{verbatim}
120    Event: FullyBooted
121    Privilege: system,all
122    Status: Fully Booted
123 \end{verbatim}
124
125 \section{Device status reports}
126
127
128 \section{Some standard AMI headers}
129 \begin{verbatim}
130  Account:                 -- Account Code (Status)
131  AccountCode:             -- Account Code (cdr_manager)
132  ACL: <Y | N>             -- Does ACL exist for object ?
133  Action: <action>         -- Request or notification of a particular action
134  Address-IP:              -- IPaddress
135  Address-Port:            -- IP port number
136  Agent: <string>          -- Agent name
137  AMAflags:                -- AMA flag (cdr_manager, sippeers)
138  AnswerTime:              -- Time of answer (cdr_manager)
139  Append: <bool>           -- CDR userfield Append flag
140  Application:             -- Application to use
141  Async:                   -- Whether or not to use fast setup
142  AuthType:                -- Authentication type (for login or challenge)
143           "md5"
144  BillableSeconds:         -- Billable seconds for call (cdr_manager)
145  CallerID:                -- Caller id (name and number in Originate & cdr_manager)
146  CallerID:                -- CallerID number
147                              Number or "<unknown>" or "unknown"
148                              (should change to "<unknown>" in app_queue)
149  CallerID1:               -- Channel 1 CallerID (Link event)
150  CallerID2:               -- Channel 2 CallerID (Link event)
151  CallerIDName:            -- CallerID name
152                              Name or "<unknown>" or "unknown"
153                              (should change to "<unknown>" in app_queue)
154  Callgroup:               -- Call group for peer/user
155  CallsTaken: <num>        -- Queue status variable
156  Cause: <value>           -- Event change cause - "Expired"
157  Cause: <value>           -- Hangupcause (channel.c)
158  CID-CallingPres:         -- Caller ID calling presentation
159  Channel: <channel>       -- Channel specifier
160  Channel: <dialstring>    -- Dialstring in Originate
161  Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
162  Channel: <tech>          -- Technology (SIP/IAX2 etc) in Registry events
163  ChannelType:             -- Tech: SIP, IAX2, DAHDI, MGCP etc
164  Channel1:                -- Link channel 1
165  Channel2:                -- Link channel 2
166  ChanObjectType:          -- "peer", "user"
167  Codecs:                  -- Codec list
168  CodecOrder:              -- Codec order, separated with comma ","
169  Command:                 -- Cli command to run
170  Context:                 -- Context
171  Count: <num>             -- Number of callers in queue
172  Data:                    -- Application data
173  Default-addr-IP:         -- IP address to use before registration
174  Default-Username:        -- Username part of URI to use before registration
175  Destination:             -- Destination for call (Dialstring ) (dial, cdr_manager)
176  DestinationContext:      -- Destination context (cdr_manager)
177  DestinationChannel:      -- Destination channel (cdr_manager)
178  DestUniqueID:            -- UniqueID of destination (dial event)
179  Direction: <type>        -- Audio to mute (read | write | both) 
180  Disposition:             -- Call disposition (CDR manager)
181  Domain: <domain>         -- DNS domain
182  Duration: <secs>         -- Duration of call (cdr_manager)
183  Dynamic: <Y |  N>        -- Device registration supported?
184  Endtime:                 -- End time stamp of call (cdr_manager)
185  EventList: <flag>        -- Flag being "Start", "End", "Cancelled" or "ListObject"
186  Events: <eventmask>      -- Eventmask filter ("on", "off", "system", "call", "log")
187  Exten:                   -- Extension (Redirect command)
188  Extension:               -- Extension (Status)
189  Family: <string>         -- ASTdb key family
190  File: <filename>         -- Filename (monitor)
191  Format: <format>         -- Format of sound file (monitor)
192  From: <time>             --  Parking time (ParkedCall event)
193  Hint:                    -- Extension hint
194  Incominglimit:           -- SIP Peer incoming limit
195  Key:
196  Key:                     -- ASTdb Database key
197  LastApplication:         -- Last application executed (cdr_manager)
198  LastCall: <num>          -- Last call in queue
199  LastData:                -- Data for last application (cdr_manager)
200  Link:                    -- (Status)
201  ListItems: <number>      -- Number of items in Eventlist (Optionally sent in "end" packet)
202  Location:                -- Interface (whatever that is -maybe tech/name in app_queue )
203  Loginchan:               -- Login channel for agent
204  Logintime: <number>      -- Login time for agent
205  Mailbox:                 -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
206  MD5SecretExist: <Y | N>  -- Whether secret exists in MD5 format
207  Membership: <string>     -- "Dynamic" or "static" member in queue
208  Message: <text>          -- Text message in ACKs, errors (explanation)
209  Mix: <bool>              -- Boolean parameter (monitor)
210  MOHSuggest:              -- Suggested music on hold class for peer (mohsuggest)
211  NewMessages: <count>     -- Count of new Mailbox messages (mailboxcount)
212  Newname:
213  ObjectName:              -- Name of object in list
214  OldName:                 -- Something in Rename (channel.c)
215  OldMessages: <count>     -- Count of old mailbox messages (mailboxcount)
216  Outgoinglimit:           -- SIP Peer outgoing limit
217  Paused: <num>            -- Queue member paused status
218  Peer: <tech/name>        -- "channel" specifier :-)
219  PeerStatus: <tech/name>  -- Peer status code
220                            "Unregistered", "Registered", "Lagged", "Reachable"
221  Penalty: <num>           -- Queue penalty
222  Priority:                -- Extension priority
223  Privilege: <privilege>   -- AMI authorization class (system, call, log, verbose, command, agent, user)
224  Pickupgroup:             -- Pickup group for peer
225  Position: <num>          -- Position in Queue
226  Queue:                   -- Queue name
227  Reason:                  -- "Autologoff"
228  Reason:                  -- "Chanunavail"
229  Response: <response>     -- response code, like "200 OK"
230                            "Success", "Error", "Follows"
231  Restart:                 -- "True", "False"
232  RegExpire:               -- SIP registry expire
233  RegExpiry:               -- SIP registry expiry
234  Reason:                  -- Originate reason code
235  Seconds:                 -- Seconds (Status)
236  Secret: <password>       -- Authentication secret (for login)
237  SecretExist: <Y | N>     -- Whether secret exists
238  Shutdown:                -- "Uncleanly", "Cleanly"
239  SIP-AuthInsecure:
240  SIP-FromDomain:          -- Peer FromDomain
241  SIP-FromUser:            -- Peer FromUser
242  SIP-NatSupport:
243  SIPLastMsg:
244  Source:                  -- Source of call (dial event, cdr_manager)
245  SrcUniqueID:             -- UniqueID of source (dial event)
246  StartTime:               -- Start time of call (cdr_manager)
247  State:                   -- Channel state
248  State: <1 | 0>           -- Mute flag
249  Status:                  -- Registration status (Registry events SIP)
250  Status:                  -- Extension status (Extensionstate)
251  Status:                  -- Peer status (if monitored)  ** Will change name **
252                              "unknown", "lagged", "ok"
253  Status: <num>            -- Queue Status
254  Status:                  -- DND status (DNDState)
255  Time: <sec>              -- Roundtrip time (latency)
256  Timeout:                 -- Parking timeout time
257  Timeout:                 -- Timeout for call setup (Originate)
258  Timeout: <seconds>       -- Timeout for call
259  Uniqueid:                -- Channel Unique ID
260  Uniqueid1:               -- Channel 1 Unique ID (Link event)
261  Uniqueid2:               -- Channel 2 Unique ID (Link event)
262  User:                    -- Username (SIP registry)
263  UserField:               -- CDR userfield (cdr_manager)
264  Val:                     -- Value to set/read in ASTdb
265  Variable:                -- Variable AND value to set (multiple separated with | in Originate)
266  Variable: <name>         -- For channel variables
267  Value: <value>           -- Value to set
268  VoiceMailbox:            -- VM Mailbox in SIPpeers
269  Waiting:                 -- Count of mailbox messages (mailboxstatus)
270 \end{verbatim}
271
272  ** Please try to re-use existing headers to simplify manager message parsing in clients.
273
274 Read the CODING-GUIDELINES if you develop new manager commands or events.