Rewrote a large portion of the existing documentation and added information about the TCP/IP socket interface git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@240973 65c4cc65-6c06-0410-ace0-fbb531ad65f3
192 lines
7.4 KiB
Text
192 lines
7.4 KiB
Text
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
|
|
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 '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 'H' command logs the supplied message to the Asterisk log, stops
|
|
the generator, hangs up the channel and terminates the ExternalIVR
|
|
application.
|
|
|
|
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 get 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.
|