Automatically create new buddy upon reception of a presence stanza of
[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: Zap/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, ZAP, 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  Disposition:             -- Call disposition (CDR manager)
167  Domain: <domain>         -- DNS domain
168  Duration: <secs>         -- Duration of call (cdr_manager)
169  Dynamic: <Y |  N>        -- Device registration supported?
170  Endtime:                 -- End time stamp of call (cdr_manager)
171  EventList: <flag>        -- Flag being "Start", "End", "Cancelled" or "ListObject"
172  Events: <eventmask>      -- Eventmask filter ("on", "off", "system", "call", "log")
173  Exten:                   -- Extension (Redirect command)
174  Extension:               -- Extension (Status)
175  Family: <string>         -- ASTdb key family
176  File: <filename>         -- Filename (monitor)
177  Format: <format>         -- Format of sound file (monitor)
178  From: <time>             --  Parking time (ParkedCall event)
179  Hint:                    -- Extension hint
180  Incominglimit:           -- SIP Peer incoming limit
181  Key:
182  Key:                     -- ASTdb Database key
183  LastApplication:         -- Last application executed (cdr_manager)
184  LastCall: <num>          -- Last call in queue
185  LastData:                -- Data for last application (cdr_manager)
186  Link:                    -- (Status)
187  ListItems: <number>      -- Number of items in Eventlist (Optionally sent in "end" packet)
188  Location:                -- Interface (whatever that is -maybe tech/name in app_queue )
189  Loginchan:               -- Login channel for agent
190  Logintime: <number>      -- Login time for agent
191  Mailbox:                 -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
192  MD5SecretExist: <Y | N>  -- Whether secret exists in MD5 format
193  Membership: <string>     -- "Dynamic" or "static" member in queue
194  Message: <text>          -- Text message in ACKs, errors (explanation)
195  Mix: <bool>              -- Boolean parameter (monitor)
196  NewMessages: <count>     -- Count of new Mailbox messages (mailboxcount)
197  Newname:
198  ObjectName:              -- Name of object in list
199  OldName:                 -- Something in Rename (channel.c)
200  OldMessages: <count>     -- Count of old mailbox messages (mailboxcount)
201  Outgoinglimit:           -- SIP Peer outgoing limit
202  Paused: <num>            -- Queue member paused status
203  Peer: <tech/name>        -- "channel" specifier :-)
204  PeerStatus: <tech/name>  -- Peer status code
205                            "Unregistered", "Registered", "Lagged", "Reachable"
206  Penalty: <num>           -- Queue penalty
207  Priority:                -- Extension priority
208  Privilege: <privilege>   -- AMI authorization class (system, call, log, verbose, command, agent, user)
209  Pickupgroup:             -- Pickup group for peer
210  Position: <num>          -- Position in Queue
211  Queue:                   -- Queue name
212  Reason:                  -- "Autologoff"
213  Reason:                  -- "Chanunavail"
214  Response: <response>     -- response code, like "200 OK"
215                            "Success", "Error", "Follows"
216  Restart:                 -- "True", "False"
217  RegExpire:               -- SIP registry expire
218  RegExpiry:               -- SIP registry expiry
219  Reason:                  -- Originate reason code
220  Seconds:                 -- Seconds (Status)
221  Secret: <password>       -- Authentication secret (for login)
222  SecretExist: <Y | N>     -- Whether secret exists
223  Shutdown:                -- "Uncleanly", "Cleanly"
224  SIP-AuthInsecure:
225  SIP-FromDomain:          -- Peer FromDomain
226  SIP-FromUser:            -- Peer FromUser
227  SIP-NatSupport:
228  SIPLastMsg:
229  Source:                  -- Source of call (dial event, cdr_manager)
230  SrcUniqueID:             -- UniqueID of source (dial event)
231  StartTime:               -- Start time of call (cdr_manager)
232  State:                   -- Channel state
233  Status:                  -- Registration status (Registry events SIP)
234  Status:                  -- Extension status (Extensionstate)
235  Status:                  -- Peer status (if monitored)  ** Will change name **
236                              "unknown", "lagged", "ok"
237  Status: <num>            -- Queue Status
238  Status:                  -- DND status (DNDState)
239  Time: <sec>              -- Roundtrip time (latency)
240  Timeout:                 -- Parking timeout time
241  Timeout:                 -- Timeout for call setup (Originate)
242  Timeout: <seconds>       -- Timeout for call
243  Uniqueid:                -- Channel Unique ID
244  Uniqueid1:               -- Channel 1 Unique ID (Link event)
245  Uniqueid2:               -- Channel 2 Unique ID (Link event)
246  User:                    -- Username (SIP registry)
247  UserField:               -- CDR userfield (cdr_manager)
248  Val:                     -- Value to set/read in ASTdb
249  Variable:                -- Variable AND value to set (multiple separated with | in Originate)
250  Variable: <name>         -- For channel variables
251  Value: <value>           -- Value to set
252  VoiceMailbox:            -- VM Mailbox in SIPpeers
253  Waiting:                 -- Count of mailbox messages (mailboxstatus)
254 \end{verbatim}
255
256  ** Please try to re-use existing headers to simplify manager message parsing in clients.
257
258 Read the CODING-GUIDELINES if you develop new manager commands or events.