123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153 |
- 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 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 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, 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 sent 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
- 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 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 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.
|