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