doc/externalivr.txt

   1 Asterisk External IVR Interface
   2 -------------------------------
   3
   4 If you load app_externalivr.so in your Asterisk instance, you will
   5 have an ExternalIVR() application available in your dialplan. This
   6 application implements a simple protocol for bidirectional
   7 communication with an external process, while simultaneous playing
   8 audio files to the connected channel (without interruption or
   9 blocking).
  10
  11 The arguments to ExternalIVR() consist of the command to execute and
  12 any arguments to pass to it, the same as the System() application
  13 accepts. The external command will be executed in a child process,
  14 with its standard file handles connected to the Asterisk process as
  15 follows:
  16
  17 stdin (0) - DTMF and hangup events will be received on this handle
  18 stdout (1) - Playback and hangup commands can be sent on this handle
  19 stderr (2) - Error messages can be sent on this handle
  20
  21 The application will also create an audio generator to play audio to
  22 the channel, and will start playing silence. When your application
  23 wants to send audio to the channel, it can send a command (see below)
  24 to add file(s) to the generator's playlist. The generator will then
  25 work its way through the list, playing each file in turn until it
  26 either runs out of files to play, the channel is hung up, or a command
  27 is received to clear the list and start with a new file. At any time,
  28 more files can be added to the list and the generator will play them
  29 in sequence.
  30
  31 While the generator is playing audio (or silence), any DTMF events
  32 received on the channel will be sent to the child process (see
  33 below). Note that this can happen at any time, since the generator,
  34 the child process and the channel thread are all executing
  35 independently. It is very important that your external application be
  36 ready to receive events from Asterisk at all times (without blocking),
  37 or you could cause the channel to become non-responsive.
  38
  39 If the child process dies, ExternalIVR() will notice this and hang up
  40 the channel immediately (and also send a message to the log).
  41
  42 DTMF (and other) events
  43 -----------------------
  44
  45 All events will be newline-terminated strings.
  46
  47 Events send to the child's stdin will be in the following format:
  48
  49 tag,timestamp[,data]
  50
  51 The tag can be one of the following characters:
  52
  53 0-9: DTMF event for keys 0 through 9
  54 A-D: DTMF event for keys A through D
  55 *: DTMF event for key *
  56 #: DTMF event for key #
  57 H: the channel was hung up by the connected party
  58 Z: the previous command was unable to be executed (file does not
  59 exist, etc.)
  60 T: the play list was interrupted (see below)
  61 D: a file was dropped from the play list due to interruption (the
  62 data element will be the dropped file name)
  63 F: a file has finished playing (the data element will be the file
  64 name)
  65
  66 The timestamp will be 10 digits long, and will be a decimal
  67 representation of a standard Unix epoch-based timestamp.
  68
  69 Commands
  70 --------
  71
  72 All commands must be newline-terminated strings.
  73
  74 The child process can send commands on stdout in the following formats:
  75
  76 S,filename
  77 A,filename
  78 H,message
  79 O,option
  80
  81 The 'S' command checks to see if there is a playable audio file with
  82 the specified name, and if so, clear's the generator's playlist and
  83 places the file onto the list. Note that the playability check does
  84 not take into account transcoding requirements, so it is possible for
  85 the file to not be played even though it was found. If the file cannot
  86 be found, a 'Z' event (see above) will be sent to the child. If the
  87 generator is not currently playing silence, then T and D events will
  88 be sent to the child to signal the playlist interruption and notify
  89 it of the files that will not be played.
  90
  91 The 'A' command checks to see if there is a playable audio file with
  92 the specified name, and if so, adds it to the generator's
  93 playlist. The same playability and exception rules apply as for the
  94 'S' command.
  95
  96 The 'H' command stops the generator and hangs up the channel, and logs
  97 the supplied message to the Asterisk log.
  98
  99 The 'O' command allows the child to set/clear options in the
 100 ExternalIVR() application. The supported options are:
 101         autoclear/noautoclear:
 102         Automatically interrupt and clear the playlist upon reception
 103         of DTMF input.
 104
 105 Errors
 106 ------
 107
 108 Any newline-terminated output generated by the child process on its
 109 stderr handle will be copied into the Asterisk log.