mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-31 02:37:10 +00:00
286a521e11
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@9047 65c4cc65-6c06-0410-ace0-fbb531ad65f3
110 lines
4.2 KiB
Plaintext
110 lines
4.2 KiB
Plaintext
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.
|