additional checking related to issue 17186
[asterisk/asterisk.git] / doc / externalivr.txt
1 Asterisk External IVR Interface
2 -------------------------------
3
4 If you load app_externalivr.so in your Asterisk instance, you will
5 have an ExternalIVR() application available in your dialplan. This
6 application implements a simple protocol for bidirectional
7 communication with an external process, while simultaneous playing
8 audio files to the connected channel (without interruption or
9 blocking).
10
11 There are two ways to use ExternalIVR(); you can execute an
12 application on the local system or you can establish a socket
13 connection to a TCP/IP socket server.
14
15 To execute a local application use the form:
16 ExternalIVR(/full/path/to/applcation[(arguments)],options)
17
18 The arguments are optional, however if they exist they must be
19 enclosed in parentheses. The external application will be executed
20 in a child process, with its standard file handles connected to the
21 Asterisk process as follows:
22
23 stdin (0)  - events will be received on this handle
24 stdout (1) - commands can be sent on this handle
25 stderr (2) - messages can be sent on this handle
26 * Use of stderr for message communication is discouraged because
27 it is not supported by a socket connection.
28
29 To create a socket connection use the form:
30 ExternalIVR(ivr://host[:port][(arguments)],options)
31
32 The host can be a fqdn or an ip address. The port is optional, if
33 not specified the default of 2949 will be used. The arguments are
34 optional however if they exist they must be enclosed in parentheses.
35 TheExternalIVR application will connect to the specified socket
36 server and establish a bi-directional socket connection, where
37 events will be sent to the TCP/IP server and commands received
38 from it.
39
40 The specific ExternalIVR options, events and commands are detailed
41 below.
42
43 Upon execution, if not specifically prevented by an option, the
44 ExternalIVR application will answer the channel (if it's not
45 already answered), create an audio generator, and start playing
46 silence. When your application wants to send audio to the channel,
47 it can send a command (see below) to add a file to the generator's
48 playlist. The generator will then work its way through the list,
49 playing each file in turn until it either runs out of files to
50 play, the channel is hung up, or a command is received to clear
51 the list and start with a new file. At any time, more files can
52 be added to the list and the generator will play them in sequence.
53
54 While the generator is playing audio (or silence), any DTMF events
55 received on the channel will be sent to the child process (see
56 below). Note that this can happen at any time, since the generator,
57 the child process and the channel thread are all executing
58 independently. It is very important that your external application
59 be ready to receive events from Asterisk at all times (without
60 blocking), or you could cause the channel to become non-responsive.
61
62 If the child process dies, or the remote server disconnects,
63 ExternalIVR() will notice this and hang up the channel
64 immediately (and also send a message to the log).
65
66 ExternalIVR() Options
67 ---------------------
68 n: 'n'oanswer, don't answer an otherwise unanswered channel.
69 i: 'i'gnore_hangup, instead of sending an 'H' event and exiting
70    ExternalIVR() upon channel hangup, it instead sends an 'I'
71    event and expects the external application to exit the process.
72 d: 'd'ead, allows the operation of ExternalIVR() on channels that
73    have already been hung up.
74
75 Events
76 ------
77
78 All events are be newline-terminated strings and are sent in the
79 following format:
80
81 tag,timestamp[,data]
82
83 The tag can be one of the following characters:
84
85 0-9: DTMF event for keys 0 through 9
86 A-D: DTMF event for keys A through D
87 *: DTMF event for key *
88 #: DTMF event for key #
89 H: the channel was hung up by the connected party
90 E: the script requested an exit
91 Z: the previous command was unable to be executed. There may be a
92    data element if appropriate, see specific commands below for
93    details
94 T: the play list was interrupted (see S command below)
95 D: a file was dropped from the play list due to interruption (the
96    data element will be the dropped file name) NOTE: this tag
97    conflicts with the D DTMF event tag. The existence of the data
98    element is used to differentiate between the two cases
99 F: a file has finished playing (the data element will be the file
100    name)
101 P: a response to the 'P' command (see below)
102 G: a response to the 'G' command (see below)
103 I: a Inform message, meant to "inform" the client that something
104    has occurred.  (see Inform Messages below)
105
106 The timestamp will be 10 digits long, and will be a decimal
107 representation of a standard Unix epoch-based timestamp.
108
109 Commands
110 --------
111
112 All commands are newline-terminated strings.
113
114 The child process can send one of the following commands:
115
116 S,filename
117 A,filename
118 H,message
119 E,message
120 O,option
121 V,name=value[,name=value[,name=value]]
122 G,name[,name[,name]]
123 L,log_message
124 P,TIMESTAMP
125 T,TIMESTAMP
126
127 The 'S' command checks to see if there is a playable audio file with
128 the specified name, and if so, clear's the generator's playlist and
129 places the file onto the list. Note that the playability check does
130 not take into account transcoding requirements, so it is possible for
131 the file to not be played even though it was found. If the file does
132 not exist it sends a Z response with the data element set to the file
133 requested. If the generator is not currently playing silence, then T
134 and D events will be sent to signal the playlist interruption and
135 notify it of the files that will not be played.
136
137 The 'A' command checks to see if there is a playable audio file with
138 the specified name, and if so, appends it to the generator's playlist.
139 The same playability and exception rules apply as for the 'S' command.
140
141 The 'E' command logs the supplied message to the Asterisk log, stops
142 the generator and terminates the ExternalIVR application, but continues
143 execution in the dialplan.
144
145 The 'H' command logs the supplied message to the Asterisk log, stops
146 the generator, hangs up the channel and terminates the ExternalIVR
147 application.
148
149 The 'O' command allows the child to set/clear options in the
150 ExternalIVR() application.
151
152 The supported options are:
153 (no)autoclear: Automatically interrupt and clear the playlist
154                upon reception of DTMF input.
155
156 The 'T' command will answer an unanswered channel. If it fails either
157 answering the channel or starting the generator it sends a Z response
158 of "Z,TIMESTAMP,ANSWER_FAILED" or "Z,TIMESTAMP,GENERATOR_FAILED"
159 respectively.
160
161 The 'V' command sets the specified channel variable(s) to the specified
162 value(s).
163
164 The 'G' command gets the specified channel variable(s).  Multiple
165 variables are separated by commas.  Response is in name=value format.
166
167 The 'P' command gets the parameters passed into ExternalIVR() minus
168 the options to ExternalIVR() itself:
169         If ExternalIVR() is executed as:
170                 ExternalIVR(/usr/bin/foo(arg1,arg2),n)
171         The response to the 'P' command would be:
172                 P,TIMESTAMP,/usr/bin/foo,arg1,arg2
173 NOTE: This is the only way for a TCP/IP server to be able to get retrieve
174 the arguments.
175
176 The 'L' command puts a message into the Asterisk log. NOTE: This is
177 prefered to using stderr and is the only way for a TCP/IP server to
178 log a message.
179
180 Inform Messages
181 ---------------
182
183 The only inform message that currently exists is a HANGUP message,
184 in the form I,TIMESTAMP,HANGUP and is used to inform of a hangup
185 when the i option is specified.
186
187 Errors
188 ------
189
190 Any newline-terminated output generated by the child process on its
191 stderr handle will be copied into the Asterisk log.