Asterisk External IVR Interface ------------------------------- If you load app_externalivr.so in your Asterisk instance, you will have an ExternalIVR() application available in your dialplan. This application implements a simple protocol for bidirectional communication with an external process, while simultaneous playing audio files to the connected channel (without interruption or blocking). The arguments to ExternalIVR() consist of the command to execute and any arguments to pass to it, the same as the System() application accepts. The external command can be executed in a child process, with its standard file handles connected to the Asterisk process as follows: stdin (0) - DTMF and hangup events will be received on this handle stdout (1) - Playback and hangup commands can be sent on this handle stderr (2) - Error messages can be sent on this handle The external command can also be executed on another host entirely (specified by the ivr:// prefix), with its standard file handles connected to the Asterisk process as follows: stdin (0) - DTMF and hangup events will be received on this handle stdout (1) - Playback and hangup commands can be sent on this handle There are no error messages available when using ExternalIVR over TCP, use the 'L' command as a replacement for this. The application will also create an audio generator to play audio to the channel, and will start playing silence. When your application wants to send audio to the channel, it can send a command (see below) to add file(s) to the generator's playlist. The generator will then work its way through the list, playing each file in turn until it either runs out of files to play, the channel is hung up, or a command is received to clear the list and start with a new file. At any time, more files can be added to the list and the generator will play them in sequence. While the generator is playing audio (or silence), any DTMF events received on the channel will be sent to the child process (see below). Note that this can happen at any time, since the generator, the child process and the channel thread are all executing independently. It is very important that your external application be ready to receive events from Asterisk at all times (without blocking), or you could cause the channel to become non-responsive. If the child process dies, ExternalIVR() will notice this and hang up the channel immediately (and also send a message to the log). ExternalIVR() Options ---------------------- n: 'n'oanswer, don't answer an otherwise unanswered channel. i: 'i'gnore_hangup, instead of sending an 'H' event and exiting ExternalIVR() upon channel hangup, it instead sends an 'I' event and expects the external application to exit the process. d: 'd'ead, allows the operation of ExternalIVR() on channels that have already been hung up. DTMF (and other) events ----------------------- All events will be newline-terminated strings. Events send to the child's stdin will be in the following format: tag,timestamp[,data] The tag can be one of the following characters: 0-9: DTMF event for keys 0 through 9 A-D: DTMF event for keys A through D *: DTMF event for key * #: DTMF event for key # H: the channel was hung up by the connected party E: the script requested an exit Z: the previous command was unable to be executed (file does not exist, etc.) T: the play list was interrupted (see below) D: a file was dropped from the play list due to interruption (the data element will be the dropped file name) F: a file has finished playing (the data element will be the file name) P: a response to the 'P' command (see below) G: a response to the 'G' command (see below) I: a Inform message, meant to "inform" the client that something has occured. (see Inform Messages below) The timestamp will be 10 digits long, and will be a decimal representation of a standard Unix epoch-based timestamp. Commands -------- All commands must be newline-terminated strings. The child process can send commands on stdout in the following formats: S,filename A,filename H,message E,message O,option V,name=value[,name=value[,name=value]] G,name[,name[,name]] L,log_message P,TIMESTAMP T,TIMESTAMP The 'S' command checks to see if there is a playable audio file with the specified name, and if so, clear's the generator's playlist and places the file onto the list. Note that the playability check does not take into account transcoding requirements, so it is possible for the file to not be played even though it was found. If the file cannot be found, a 'Z' event (see above) will be sent to the child. If the generator is not currently playing silence, then T and D events will be sent to the child to signal the playlist interruption and notify it of the files that will not be played. The 'A' command checks to see if there is a playable audio file with the specified name, and if so, adds it to the generator's playlist. The same playability and exception rules apply as for the 'S' command. The 'E' command stops the generator and continues execution in the dialplan, and logs the supplied message to the Asterisk log. The 'H' command stops the generator and hangs up the channel, and logs the supplied message to the Asterisk log. The 'O' command allows the child to set/clear options in the ExternalIVR() application. The supported options are: autoclear/noautoclear: Automatically interrupt and clear the playlist upon reception of DTMF input. The 'T' command will answer and unanswered channel. If it fails either answering the channel or starting the generator it sends a Z response of "Z,TIMESTAMP,ANSWER_FAILED" or "Z,TIMESTAMP,GENERATOR_FAILED" respectively. The 'V' command sets the specified channel variable(s) to the specified value(s). The 'G' command gets the specified channel variable(s). Multiple variables are separated by commas. Response is in name=value format. The 'P' command gets the parameters passed into ExternalIVR() minus the options to ExternalIVR() itself: If ExternalIVR() is executed as: ExternalIVR(/usr/bin/foo(arg1,arg2),n) The response to the 'P' command would be: P,TIMESTAMP,/usr/bin/foo|arg1|arg2 The 'L' command puts a message into the Asterisk log. Errors ------ Any newline-terminated output generated by the child process on its stderr handle will be copied into the Asterisk log.