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