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