<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/External+IVR+Interface">External IVR Interface</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~seanbright">Sean Bright</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Formatting and anchors<br />
</div>
<br/>
<h4>Changes (40)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >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: <br> <br></td></tr>
<tr><td class="diff-changed-lines" >* <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stdin<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> (0) - Events will be received on this handle <br></td></tr>
<tr><td class="diff-changed-lines" >* <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stdout<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> (1) - Commands can be sent on this handle <br></td></tr>
<tr><td class="diff-changed-lines" >* <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stderr<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> (2) - Messages can be sent on this handle <br></td></tr>
<tr><td class="diff-unchanged" > <br>{info} <br></td></tr>
<tr><td class="diff-changed-lines" >Use of <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stderr<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> for message communication is discouraged because it is not supported by a socket connection. <br></td></tr>
<tr><td class="diff-unchanged" >{info} <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The host can be a fully qualified domain name or an IP address (both IPv4 and IPv6 are supported). The port is optional and, if not specified, is {{2949}} by default. The {{ExternalIVR}} application will connect to the specified socket server and establish a bidirectional socket connection, where events will be sent to the TCP/IP server and commands received from it. <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The specific ExternalIVR options, events and commands are detailed below. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The specific {{ExternalIVR}} options, [#events] and [#commands] are detailed below. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >Upon execution, if not specifically prevented by an option, the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>ExternalIVR<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> 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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">command (see below)</span> <span class="diff-added-words"style="background-color: #dfd;">[command|#commands]</span> 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. <span class="diff-added-words"style="background-color: #dfd;"> </span> At any time, more files can be added to the list and the generator will play them in sequence. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >While the generator is playing audio (or silence), any DTMF <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">[#</span>events<span class="diff-added-chars"style="background-color: #dfd;">]</span></span> received on the channel will be sent to the child <span class="diff-changed-words">process<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;"> (see below)</span>.</span> 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. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >If the child process dies, or the remote server disconnects, <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ExternalIVR()</span> <span class="diff-added-words"style="background-color: #dfd;">{{ExternalIVR}}</span> will notice this and hang up the channel immediately (and also send a message to the log). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >h5. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ExternalIVR()</span> <span class="diff-added-words"style="background-color: #dfd;">{{ExternalIVR}}</span> Options <br></td></tr>
<tr><td class="diff-unchanged" > <br>* {{n}} - 'n'oanswer, don't answer an otherwise unanswered channel. <br></td></tr>
<tr><td class="diff-changed-lines" >* {{i}} - 'i'gnore_hangup, instead of sending an <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'H'</span> <span class="diff-added-words"style="background-color: #dfd;">{{H}}</span> event and exiting <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ExternalIVR()</span> <span class="diff-added-words"style="background-color: #dfd;">{{ExternalIVR}}</span> upon channel hangup, it instead sends an <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'I'event</span> <span class="diff-added-words"style="background-color: #dfd;">{{I}} event</span> and expects the external application to exit the process. <br></td></tr>
<tr><td class="diff-changed-lines" >* {{d}} - 'd'ead, allows the operation of <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ExternalIVR()</span> <span class="diff-added-words"style="background-color: #dfd;">{{ExternalIVR}}</span> on channels that have already been hung up. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:events} <br></td></tr>
<tr><td class="diff-unchanged" >h5. Events <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* {{E}} - The script requested an exit <br>* {{Z}} - The previous command was unable to be executed. There may be a data element if appropriate, see specific commands below for details <br></td></tr>
<tr><td class="diff-changed-lines" >* {{T}} - The play list was interrupted (see <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">S command below)</span> <span class="diff-added-words"style="background-color: #dfd;">[{{S}} command|#S-command])</span> <br></td></tr>
<tr><td class="diff-changed-lines" >* {{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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">D</span> <span class="diff-added-words"style="background-color: #dfd;">{{D}}</span> DTMF event tag. The existence of the data element is used to differentiate between the two cases <br></td></tr>
<tr><td class="diff-unchanged" >* {{F}} - A file has finished playing (the data element will be the file name) <br></td></tr>
<tr><td class="diff-changed-lines" >* {{P}} - A response to the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'P' command (see below)</span> <span class="diff-added-words"style="background-color: #dfd;">[{{P}} command|#P-command]</span> <br></td></tr>
<tr><td class="diff-changed-lines" >* {{G}} - A response to the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'G' command (see below)</span> <span class="diff-added-words"style="background-color: #dfd;">[{{G}} command|#G-command]</span> <br></td></tr>
<tr><td class="diff-unchanged" >* {{I}} - A Inform message, meant to "inform" the client that something has occurred. (see Inform Messages below) <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The timestamp will be 10 digits long, and will be a decimal representation of a standard Unix epoch-based timestamp. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The timestamp will be a decimal representation of the standard Unix epoch-based timestamp, e.g., {{284654100}}. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:commands} <br></td></tr>
<tr><td class="diff-unchanged" >h5. Commands <br> <br></td></tr>
<tr><td class="diff-changed-lines" >All commands are newline-terminated <span class="diff-added-words"style="background-color: #dfd;">({{\n}})</span> strings. <br></td></tr>
<tr><td class="diff-unchanged" > <br>The child process can send one of the following commands: <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* {{T,TIMESTAMP}} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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 <br>and D events will be sent to signal the playlist interruption and notify it of the files that will not be played. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:S-command}The {{S}} command checks to see if there is a playable audio file with the specified name, and if so, clears 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. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'A'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:A-command}The {{A}}</span> 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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'S'</span> <span class="diff-added-words"style="background-color: #dfd;">{{S}}</span> command. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'E'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:E-command}The {{E}}</span> command logs the supplied message to the Asterisk log, stops the generator and terminates the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>ExternalIVR<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> application, but continues execution in the dialplan. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'H'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:H-command}The {{H}}</span> command logs the supplied message to the Asterisk log, stops the generator, hangs up the channel and terminates the ExternalIVR application. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'O'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:O-command}The {{O}}</span> command allows the child to set/clear options in the ExternalIVR() application. The supported options are: <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">(no)autoclear:</span> <span class="diff-added-words"style="background-color: #dfd;">* {{(no)autoclear}} -</span> Automatically interrupt and clear the playlist upon reception of DTMF input. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:T-command}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. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'V'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:V-command}The {{V}}</span> command sets the specified channel variable(s) to the specified value(s). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'G'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:G-command}The {{G}}</span> command gets the specified channel variable(s). Multiple variables are separated by commas. Response is in <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>name=value<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> format. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'P' command gets the parameters passed into ExternalIVR() minus the options to ExternalIVR() itself: <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:P-command}The {{P}} command gets the parameters passed into {{ExternalIVR}} minus the options to {{ExternalIVR}} itself: <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >If <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ExternalIVR()</span> <span class="diff-added-words"style="background-color: #dfd;">{{ExternalIVR}}</span> is executed as: <br></td></tr>
<tr><td class="diff-unchanged" >{code} <br>ExternalIVR(/usr/bin/foo(arg1,arg2),n) <br>{code} <br></td></tr>
<tr><td class="diff-changed-lines" >The response to the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">'P'</span> <span class="diff-added-words"style="background-color: #dfd;">{{P}}</span> command would be: <br></td></tr>
<tr><td class="diff-unchanged" >{code} <br>P,TIMESTAMP,/usr/bin/foo,arg1,arg2 <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{note}This is the only way for a TCP/IP server to be able to get retrieve the arguments.{note} <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">The 'L'</span> <span class="diff-added-words"style="background-color: #dfd;">{anchor:L-command}The {{L}}</span> command puts a message into the Asterisk log. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >{note}This is preferred to using <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stderr<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> and is the only way for a TCP/IP server to log a message.{note} <br></td></tr>
<tr><td class="diff-unchanged" > <br>h5. Inform Messages <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The only inform message that currently exists is a <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>HANGUP<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> message, in the form <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>I,TIMESTAMP,HANGUP<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> and is used to inform of a hangup when the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">i</span> <span class="diff-added-words"style="background-color: #dfd;">{{i}}</span> option is specified. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h5. Errors <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Any newline-terminated <span class="diff-added-words"style="background-color: #dfd;">({{\n}})</span> output generated by the child process on its <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>stderr<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> handle will be copied into the Asterisk log. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="ExternalIVRInterface-AsteriskExternalIVRInterface"></a>Asterisk External IVR Interface</h1>
<p>If you load <tt>app_externalivr.so</tt> in your Asterisk instance, you will have an <tt>ExternalIVR</tt> application available in your dialplan. This application implements a simple protocol for bidirectional communication with an external process, while simultaneously playing audio files to the connected channel (without interruption or blocking).</p>
<p>There are two ways to use <tt>ExternalIVR</tt>; you can execute an application on the local system or you can establish a socket connection to a TCP/IP socket server.</p>
<p>To execute a local application use the form:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">ExternalIVR(/full/path/to/applcation[(arguments)],options)</pre>
</div></div>
<p>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:</p>
<ul>
<li><tt>stdin</tt> (0) - Events will be received on this handle</li>
<li><tt>stdout</tt> (1) - Commands can be sent on this handle</li>
<li><tt>stderr</tt> (2) - Messages can be sent on this handle</li>
</ul>
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Use of <tt>stderr</tt> for message communication is discouraged because it is not supported by a socket connection.</td></tr></table></div>
<p>To create a socket connection use the form:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">ExternalIVR(ivr://host[:port][(arguments)],options)</pre>
</div></div>
<p>The host can be a fully qualified domain name or an IP address (both IPv4 and IPv6 are supported). The port is optional and, if not specified, is <tt>2949</tt> by default. The <tt>ExternalIVR</tt> application will connect to the specified socket server and establish a bidirectional socket connection, where events will be sent to the TCP/IP server and commands received from it.</p>
<p>The specific <tt>ExternalIVR</tt> options, <a href="#ExternalIVRInterface-events">events</a> and <a href="#ExternalIVRInterface-commands">commands</a> are detailed below.</p>
<p>Upon execution, if not specifically prevented by an option, the <tt>ExternalIVR</tt> 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 <a href="#ExternalIVRInterface-commands">command</a> 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.</p>
<p>While the generator is playing audio (or silence), any DTMF <a href="#ExternalIVRInterface-events">events</a> received on the channel will be sent to the child process. 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.</p>
<p>If the child process dies, or the remote server disconnects, <tt>ExternalIVR</tt> will notice this and hang up the channel immediately (and also send a message to the log). </p>
<h5><a name="ExternalIVRInterface-%7B%7BExternalIVR%7D%7DOptions"></a><tt>ExternalIVR</tt> Options</h5>
<ul>
<li><tt>n</tt> - 'n'oanswer, don't answer an otherwise unanswered channel.</li>
<li><tt>i</tt> - 'i'gnore_hangup, instead of sending an <tt>H</tt> event and exiting <tt>ExternalIVR</tt> upon channel hangup, it instead sends an <tt>I</tt> event and expects the external application to exit the process.</li>
<li><tt>d</tt> - 'd'ead, allows the operation of <tt>ExternalIVR</tt> on channels that have already been hung up.</li>
</ul>
<p><a name="ExternalIVRInterface-events"></a></p>
<h5><a name="ExternalIVRInterface-Events"></a>Events</h5>
<p>All events are be newline-terminated strings and are sent in the following format:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">tag,timestamp[,data]</pre>
</div></div>
<p>The tag can be one of the following characters:</p>
<ul>
<li><tt>0-9</tt> - DTMF event for keys 0 through 9</li>
<li><tt>A-D</tt> - DTMF event for keys A through D</li>
<li><tt>*</tt> - DTMF event for key *</li>
<li><tt>#</tt> - DTMF event for key #</li>
<li><tt>H</tt> - The channel was hung up by the connected party</li>
<li><tt>E</tt> - The script requested an exit</li>
<li><tt>Z</tt> - The previous command was unable to be executed. There may be a data element if appropriate, see specific commands below for details</li>
<li><tt>T</tt> - The play list was interrupted (see <a href="#ExternalIVRInterface-Scommand"><tt>S</tt> command</a>)</li>
<li><tt>D</tt> - 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 <tt>D</tt> DTMF event tag. The existence of the data element is used to differentiate between the two cases</li>
<li><tt>F</tt> - A file has finished playing (the data element will be the file name)</li>
<li><tt>P</tt> - A response to the <a href="#ExternalIVRInterface-Pcommand"><tt>P</tt> command</a></li>
<li><tt>G</tt> - A response to the <a href="#ExternalIVRInterface-Gcommand"><tt>G</tt> command</a></li>
<li><tt>I</tt> - A Inform message, meant to "inform" the client that something has occurred. (see Inform Messages below)</li>
</ul>
<p>The timestamp will be a decimal representation of the standard Unix epoch-based timestamp, e.g., <tt>284654100</tt>.</p>
<p><a name="ExternalIVRInterface-commands"></a></p>
<h5><a name="ExternalIVRInterface-Commands"></a>Commands</h5>
<p>All commands are newline-terminated (<tt>\n</tt>) strings.</p>
<p>The child process can send one of the following commands:</p>
<ul>
<li><tt>S,filename</tt></li>
<li><tt>A,filename</tt></li>
<li><tt>H,message</tt></li>
<li><tt>E,message</tt></li>
<li><tt>O,option</tt></li>
<li><tt>V,name=value[,name=value[,name=value]]</tt></li>
<li><tt>G,name[,name[,name]]</tt></li>
<li><tt>L,log_message</tt></li>
<li><tt>P,TIMESTAMP</tt></li>
<li><tt>T,TIMESTAMP</tt></li>
</ul>
<p><a name="ExternalIVRInterface-Scommand"></a>The <tt>S</tt> command checks to see if there is a playable audio file with the specified name, and if so, clears 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 <tt>Z</tt> response with the data element set to the file requested. If the generator is not currently playing silence, then <tt>T</tt> and <tt>D</tt> events will be sent to signal the playlist interruption and notify it of the files that will not be played.</p>
<p><a name="ExternalIVRInterface-Acommand"></a>The <tt>A</tt> 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 <tt>S</tt> command.</p>
<p><a name="ExternalIVRInterface-Ecommand"></a>The <tt>E</tt> command logs the supplied message to the Asterisk log, stops the generator and terminates the <tt>ExternalIVR</tt> application, but continues execution in the dialplan.</p>
<p><a name="ExternalIVRInterface-Hcommand"></a>The <tt>H</tt> command logs the supplied message to the Asterisk log, stops the generator, hangs up the channel and terminates the ExternalIVR application.</p>
<p><a name="ExternalIVRInterface-Ocommand"></a>The <tt>O</tt> command allows the child to set/clear options in the ExternalIVR() application. The supported options are:</p>
<ul>
<li><tt>(no)autoclear</tt> - Automatically interrupt and clear the playlist upon reception of DTMF input.</li>
</ul>
<p><a name="ExternalIVRInterface-Tcommand"></a>The <tt>T</tt> command will answer an unanswered channel. If it fails either answering the channel or starting the generator it sends a <tt>Z</tt> response of <tt>Z,TIMESTAMP,ANSWER_FAILED</tt> or <tt>Z,TIMESTAMP,GENERATOR_FAILED</tt> respectively.</p>
<p><a name="ExternalIVRInterface-Vcommand"></a>The <tt>V</tt> command sets the specified channel variable(s) to the specified value(s).</p>
<p><a name="ExternalIVRInterface-Gcommand"></a>The <tt>G</tt> command gets the specified channel variable(s). Multiple variables are separated by commas. Response is in <tt>name=value</tt> format.</p>
<p><a name="ExternalIVRInterface-Pcommand"></a>The <tt>P</tt> command gets the parameters passed into <tt>ExternalIVR</tt> minus the options to <tt>ExternalIVR</tt> itself:</p>
<p>If <tt>ExternalIVR</tt> is executed as:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">ExternalIVR(/usr/bin/foo(arg1,arg2),n)</pre>
</div></div>
<p>The response to the <tt>P</tt> command would be:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">P,TIMESTAMP,/usr/bin/foo,arg1,arg2</pre>
</div></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This is the only way for a TCP/IP server to be able to get retrieve the arguments.</td></tr></table></div>
<p><a name="ExternalIVRInterface-Lcommand"></a>The <tt>L</tt> command puts a message into the Asterisk log.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This is preferred to using <tt>stderr</tt> and is the only way for a TCP/IP server to log a message.</td></tr></table></div>
<h5><a name="ExternalIVRInterface-InformMessages"></a>Inform Messages</h5>
<p>The only inform message that currently exists is a <tt>HANGUP</tt> message, in the form <tt>I,TIMESTAMP,HANGUP</tt> and is used to inform of a hangup when the <tt>i</tt> option is specified.</p>
<h5><a name="ExternalIVRInterface-Errors"></a>Errors</h5>
<p>Any newline-terminated (<tt>\n</tt>) output generated by the child process on its <tt>stderr</tt> handle will be copied into the Asterisk log.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/External+IVR+Interface">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=4260001&revisedVersion=4&originalVersion=3">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/External+IVR+Interface?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>