From 0c43a5ab3637e311a9232ae77ecd8e7f05c2f8cc Mon Sep 17 00:00:00 2001 From: oej Date: Wed, 1 Feb 2006 17:49:02 +0000 Subject: - Removing the "README." from the name of the README files. git-svn-id: http://svn.digium.com/svn/asterisk/trunk@9047 f38db490-d61c-443f-a65b-d21fe96a405b --- doc/externalivr.txt | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 doc/externalivr.txt (limited to 'doc/externalivr.txt') diff --git a/doc/externalivr.txt b/doc/externalivr.txt new file mode 100644 index 000000000..a1d4757e7 --- /dev/null +++ b/doc/externalivr.txt @@ -0,0 +1,109 @@ +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 will 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 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). + +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 +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) + +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 +O,option + +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 '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. + +Errors +------ + +Any newline-terminated output generated by the child process on its +stderr handle will be copied into the Asterisk log. -- cgit v1.2.3