diff options
Diffstat (limited to 'doc/externalivr.txt')
| -rw-r--r-- | doc/externalivr.txt | 197 |
1 files changed, 0 insertions, 197 deletions
diff --git a/doc/externalivr.txt b/doc/externalivr.txt deleted file mode 100644 index d0fd34246..000000000 --- a/doc/externalivr.txt +++ /dev/null @@ -1,197 +0,0 @@ -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). - -There are two ways to use ExternalIVR(); you can execute an -application on the local system or you can establish a socket -connection to a TCP/IP socket server. - -To execute a local application use the form: -ExternalIVR(/full/path/to/applcation[(arguments)],options) - -The arguments are optional, however if they exist they must be -enclosed in parentheses. The external application will be executed -in a child process, with its standard file handles connected to the -Asterisk process as follows: - -stdin (0) - events will be received on this handle -stdout (1) - commands can be sent on this handle -stderr (2) - messages can be sent on this handle -* Use of stderr for message communication is discouraged because -it is not supported by a socket connection. - -To create a socket connection use the form: -ExternalIVR(ivr://host[:port][(arguments)],options) - -The host can be a fqdn or an ip address. The port is optional, if -not specified the default of 2949 will be used. The arguments are -optional however if they exist they must be enclosed in parentheses. -TheExternalIVR application will connect to the specified socket -server and establish a bi-directional socket connection, where -events will be sent to the TCP/IP server and commands received -from it. - -The specific ExternalIVR options, events and commands are detailed -below. - -Upon execution, if not specifically prevented by an option, the -ExternalIVR application will answer the channel (if it's not -already answered), create an audio generator, and start playing -silence. When your application wants to send audio to the channel, -it can send a command (see below) to add a file 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, or the remote server disconnects, -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. - -Events ------- - -All events are be newline-terminated strings and are sent 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. There may be a - data element if appropriate, see specific commands below for - details -T: the play list was interrupted (see S command below) -D: a file was dropped from the play list due to interruption (the - data element will be the dropped file name) NOTE: this tag - conflicts with the D DTMF event tag. The existence of the data - element is used to differentiate between the two cases -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 occurred. (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 are newline-terminated strings. - -The child process can send one of the following commands: - -S,filename -A,filename -H,message -E,message -D,dtmf[,interval][,duration] -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 does -not exist it sends a Z response with the data element set to the file -requested. If the generator is not currently playing silence, then T -and D events will be sent 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, appends it to the generator's playlist. -The same playability and exception rules apply as for the 'S' command. - -The 'H' command logs the supplied message to the Asterisk log, stops -the generator, hangs up the channel and terminates the ExternalIVR -application. - -The 'E' command logs the supplied message to the Asterisk log, stops -the generator and terminates the ExternalIVR application, but continues -execution in the dialplan. - -The 'D' command generates DTMF on the channel, dtmf is a string of one or -more valid DTMF digits, w can be used for a half second pause. Interval -is optional, defaults to 250 milliseconds and is the time between digits. -Duration is optional and is the duration of each digit. - -The 'O' command allows the child to set/clear options in the -ExternalIVR() application. - -The supported options are: -(no)autoclear: Automatically interrupt and clear the playlist - upon reception of DTMF input. - -The 'T' command will answer an 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 -NOTE: This is the only way for a TCP/IP server to be able to retrieve -the arguments. - -The 'L' command puts a message into the Asterisk log. NOTE: This is -prefered to using stderr and is the only way for a TCP/IP server to -log a message. - -Inform Messages ---------------- - -The only inform message that currently exists is a HANGUP message, -in the form I,TIMESTAMP,HANGUP and is used to inform of a hangup -when the i option is specified. - -Errors ------- - -Any newline-terminated output generated by the child process on its -stderr handle will be copied into the Asterisk log. |