bac315b839bff25987b89a21223348c358152b29
[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 The arguments to ExternalIVR() consist of the command to execute and
12 any arguments to pass to it, the same as the System() application
13 accepts. The external command can be executed in a child process,
14 with its standard file handles connected to the Asterisk process as
15 follows:
16
17 stdin (0) - DTMF and hangup events will be received on this handle
18 stdout (1) - Playback and hangup commands can be sent on this handle
19 stderr (2) - Error messages can be sent on this handle
20
21 The external command can also be executed on another host entirely
22 (specified by the ivr:// prefix), with its standard file handles
23 connected to the Asterisk process as follows:
24
25 stdin (0) - DTMF and hangup events will be received on this handle
26 stdout (1) - Playback and hangup commands can be sent on this handle
27 There are no error messages available when using ExternalIVR over TCP,
28 use the 'L' command as a replacement for this.
29
30 The application will also create an audio generator to play audio to
31 the channel, and will start playing silence. When your application
32 wants to send audio to the channel, it can send a command (see below)
33 to add file(s) to the generator's playlist. The generator will then
34 work its way through the list, playing each file in turn until it
35 either runs out of files to play, the channel is hung up, or a command
36 is received to clear the list and start with a new file. At any time,
37 more files can be added to the list and the generator will play them
38 in sequence.
39
40 While the generator is playing audio (or silence), any DTMF events
41 received on the channel will be sent to the child process (see
42 below). Note that this can happen at any time, since the generator,
43 the child process and the channel thread are all executing
44 independently. It is very important that your external application be
45 ready to receive events from Asterisk at all times (without blocking),
46 or you could cause the channel to become non-responsive.
47
48 If the child process dies, ExternalIVR() will notice this and hang up
49 the channel immediately (and also send a message to the log).
50
51 ExternalIVR() Options
52 ----------------------
53 n: 'n'oanswer, don't answer an otherwise unanswered channel.
54 i: 'i'gnore_hangup, instead of sending an 'H' event and exiting
55 ExternalIVR() upon channel hangup, it instead sends an 'I' event
56 and expects the external application to exit the process.
57 d: 'd'ead, allows the operation of ExternalIVR() on channels that
58 have already been hung up.
59
60 DTMF (and other) events
61 -----------------------
62
63 All events will be newline-terminated strings.
64
65 Events sent to the child's stdin will be in the following format:
66
67 tag,timestamp[,data]
68
69 The tag can be one of the following characters:
70
71 0-9: DTMF event for keys 0 through 9
72 A-D: DTMF event for keys A through D
73 *: DTMF event for key *
74 #: DTMF event for key #
75 H: the channel was hung up by the connected party
76 E: the script requested an exit
77 Z: the previous command was unable to be executed (file does not
78 exist, etc.)
79 T: the play list was interrupted (see S command below)
80 D: a file was dropped from the play list due to interruption (the
81 data element will be the dropped file name) NOTE: this tag conflicts
82 with the D DTMF event tag. The existence of the data element is used
83 to differentiate between the two cases
84 F: a file has finished playing (the data element will be the file
85 name)
86 P: a response to the 'P' command (see below)
87 G: a response to the 'G' command (see below)
88 I: a Inform message, meant to "inform" the client that something
89 has occured.  (see Inform Messages below)
90
91 The timestamp will be 10 digits long, and will be a decimal
92 representation of a standard Unix epoch-based timestamp.
93
94 Commands
95 --------
96
97 All commands must be newline-terminated strings.
98
99 The child process can send commands on stdout in the following formats:
100
101 S,filename
102 A,filename
103 H,message
104 E,message
105 O,option
106 V,name=value[,name=value[,name=value]]
107 G,name[,name[,name]]
108 L,log_message
109 P,TIMESTAMP
110 T,TIMESTAMP
111
112 The 'S' command checks to see if there is a playable audio file with
113 the specified name, and if so, clear's the generator's playlist and
114 places the file onto the list. Note that the playability check does
115 not take into account transcoding requirements, so it is possible for
116 the file to not be played even though it was found. If the file cannot
117 be found, a 'Z' event (see above) will be sent to the child. If the
118 generator is not currently playing silence, then T and D events will
119 be sent to the child to signal the playlist interruption and notify
120 it of the files that will not be played.
121
122 The 'A' command checks to see if there is a playable audio file with
123 the specified name, and if so, adds it to the generator's
124 playlist. The same playability and exception rules apply as for the
125 'S' command.
126
127 The 'E' command stops the generator and continues execution in the dialplan,
128 and logs the supplied message to the Asterisk log.
129
130 The 'H' command stops the generator and hangs up the channel, and logs
131 the supplied message to the Asterisk log.
132
133 The 'O' command allows the child to set/clear options in the
134 ExternalIVR() application. The supported options are:
135         autoclear/noautoclear:
136         Automatically interrupt and clear the playlist upon reception
137         of DTMF input.
138
139 The 'T' command will answer and unanswered channel.  If it fails either
140 answering the channel or starting the generator it sends a Z response
141 of "Z,TIMESTAMP,ANSWER_FAILED" or "Z,TIMESTAMP,GENERATOR_FAILED"
142 respectively.
143
144 The 'V' command sets the specified channel variable(s) to the specified
145 value(s).
146
147 The 'G' command gets the specified channel variable(s).  Multiple
148 variables are separated by commas.  Response is in name=value format.
149
150 The 'P' command gets the parameters passed into ExternalIVR() minus
151 the options to ExternalIVR() itself:
152         If ExternalIVR() is executed as:
153                 ExternalIVR(/usr/bin/foo(arg1,arg2),n)
154         The response to the 'P' command would be:
155                 P,TIMESTAMP,/usr/bin/foo|arg1|arg2
156
157 The 'L' command puts a message into the Asterisk log.
158
159 Errors
160 ------
161
162 Any newline-terminated output generated by the child process on its
163 stderr handle will be copied into the Asterisk log.