- committed Nicholas Bachmann's docs on Auto-Dialout (Call Files)
posted to the mailing list on Feb 21, 2004
Index: advanced-config.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/advanced-config.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** advanced-config.xml 11 Jan 2004 08:04:36 -0000 1.1
--- advanced-config.xml 20 Mar 2004 17:32:12 -0000 1.2
***************
*** 641,643 ****
--- 641,755 ----
</sect2>
</sect1>
+ <sect1>
+ <title>Auto-Dialout (Call Files)</title>
+ <!-- Perhaps we should put this in the AGI chapter and rename the whole thing "Asterisk Scripting"? -->
+ <para>
+ Auto-Dialout is a feature that allows users to initiate calls through
+ Asterisk. By placing files in
+ <filename class='directory'>/var/spool/asterisk/outgoing/</filename>,
+ Asterisk can automatically initiate calls. Reported practical uses for
+ call files include automated surveys and automated voicemail callbacks.
+ </para>
+ <para>
+ In general terms, call files specify an channel to call and an
+ extension or application to connect with the called channel. All call
+ files must have both to be valid. Call files also may specify call
+ options such as Caller*ID or set local <!--right word?--> variables.
+ Statements are made in format <function>directive: arguments</function>
+ Here is a summary of available call file directives:
+ <table frame='all'>
+ <title>Call File Directives</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Explanation/Notes</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Channel: <channel></entry>
+ <entry>Outbound channel</entry>
+ </row>
+ <row>
+ <entry>Callerid: <id></entry>
+ <entry>Caller*ID for outbound channel</entry>
+ </row>
+ <row>
+ <entry>Application: <application></entry>
+ <entry>Application to bridge outbound channel with. Arguments are passed with a Data directive. See note about CDR below.</entry>
+ </row>
+ <row>
+ <entry>Data: <data></entry>
+ <entry>The data to be passed to an application</entry>
+ </row>
+ <row>
+ <entry>MaxRetries: <integer></entry>
+ <entry>Number of times to retry outbound channel if it is busy or otherwise unavailable</entry>
+ </row>
+ <row>
+ <entry>Context: <context></entry>
+ <entry>Context for an extension to bridge the outbound call to</entry>
+ </row>
+ <row>
+ <entry>Extension: <extension></entry>
+ <entry>Extension in [<context>] to bridge to</entry>
+ </row>
+ <row>
+ <entry>Priority: <integer></entry>
+ <entry>The priority in <extension>@[<context>] to connect to.</entry>
+ </row>
+ <row>
+ <entry>RetryTime: <seconds></entry>
+ <entry>Time between retries</entry>
+ </row>
+ <row>
+ <entry>WaitTime: <seconds></entry>
+ <entry>How long to wait for an answer</entry>
+ </row>
+
+ <row>
+ <entry>Context: <context></entry>
+ <entry>Context for an extension to bridge the outbound call to</entry>
+ </row>
+ <row>
+ <entry>SetVar: <name=value></entry>
+ <entry>Set a variable for the connecting dialplan or application logic to use</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ Here is an example call file:
+ <programlisting>
+ Channel: Zap/1g/12125558910
+ MaxRetries: 3
+ RetryTime: 40
+ WaitTime: 25
+ Context: surveys
+ Extension: 212
+ Priority: 1
+ </programlisting>
+ </para>
+ <sect2>
+ <title>Call File Caveats</title>
+ <para>There a few things to watch out for:</para>
+ <sect3>
+ <title>No CDR Data From Applications</title>
+ <para>
+ If your call file directly connects to an application, and
+ not an extension, no CDR data will be collected for that
+ call. To circumvent this, just connect the call to an
+ extension that starts the application.
+ </para>
+ </sect3>
+ <sect3>
+ <title>Asterisk is Quick</title>
+ <para>
+ When generating call files, create them in a staging directory and copy them into <filename class='directory'>/var/spool/asterisk/outgoing/</filename> when you are finished.
+ Otherwise, Asterisk may grab a half-way completed call file.
+ </para>
+ </sect3>
+
+ </sect2>
+ </sect1>
</chapter>
Index: agi.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/agi.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** agi.xml 11 Jan 2004 08:01:14 -0000 1.1
--- agi.xml 20 Mar 2004 17:32:12 -0000 1.2
***************
*** 15,21 ****
<para>
With AGI scripting, Asterisk passes data to your script via
! STDIN, and your script passes information back via STDOUT.
Because of this, AGI scripting can be done in almost any
! language.
</para>
<para>
--- 15,23 ----
<para>
With AGI scripting, Asterisk passes data to your script via
! STDIN, and your script passes information back via STDOUT.
! Arguments passed to the <function>agi()</function> application within
! Asterisk appear like command line arguments to the script.
Because of this, AGI scripting can be done in almost any
! language, just like CGI scripts.
</para>
<para>
***************
*** 24,29 ****
</sect1>
<sect1>
! <title>AGI examples in various languages</title>
! <para/>
<sect2>
<title>C</title>
--- 26,131 ----
</sect1>
<sect1>
! <title>AGI Basics</title>
! <para>
! Communication between the AGI script and Asterisk is accomplished
! through the standard input, output, and error file descriptors of the AGI
! script. At initialization, Asterisk sends several important pieces of
! initialization information to the AGI script. This data needs to be read
! before any commands are passed to Asterisk; otherwise, it will not be
! available.
! </para>
! <table frame='all'>
! <title>Initialization Data</title>
! <tgroup cols='3' align='left' colsep='1' rowsep='1'>
! <thead>
! <row>
! <entry>Name</entry>
! <entry>Sample Value</entry>
! <entry>Explanation/Notes</entry>
! </row>
! </thead>
! <tbody>
! <row>
! <entry>agi_accountcode</entry>
! <entry>123</entry>
! <entry>Set by SetAccount in the dialplan</entry>
! </row>
! <row>
! <entry>agi_callerid</entry>
! <entry>2128675309</entry>
! <entry>Remember, this may not always be a number</entry>
! </row>
! <row>
! <entry>agi_channel</entry>
! <entry>SIP/1001-6476</entry>
! </row>
! <row>
! <entry>agi_context</entry>
! <entry>default</entry>
! </row>
! <row>
! <entry>agi_dnid</entry>
! <entry>2890</entry>
! <entry>Dialed Number Identifier. More likely will show up as "unknown"</entry>
! </row>
! <row>
! <entry>agi_enhanced</entry>
! <entry>0.0</entry>
! <entry>Value is 1.0 if started as an EAGI script</entry>
! </row>
! <row>
! <entry>agi_extension</entry>
! <entry>100</entry>
! </row>
! <row>
! <entry>agi_language</entry>
! <entry>en</entry>
! </row>
! <row>
! <entry>agi_priority</entry>
! <entry>1</entry>
! </row>
! <row>
! <entry>agi_rdnis</entry>
! <entry>2494</entry>
! <entry>The current referring DNIS number from the Zaptel ISDN subsystem.</entry>
! </row>
! <row>
! <entry>agi_request</entry>
! <entry>myagi.agi</entry>
! <entry>???</entry>
! </row>
! <row>
! <entry>agi_type</entry>
! <entry>SIP</entry>
! <entry>Could also be ZAP, H323, etc. </entry>
! </row>
! <row>
! <entry>agi_uniqueid</entry>
! <entry>1077328545.0</entry>
! <entry>Note that uniqueids are based on Unix time.</entry>
! </row>
! </tbody>
! </tgroup>
! </table>
!
! <para>
! Commands are passed to Asterisk in the format <command>
! [command] <arg1> <arg2> ... <argn></command>.
! A list of available commands may be fetched with the Asterisk Console
! command <command>show agi</command>.
! </para>
! <para>
! The standard error channel can be used to send messages to the Asterisk
! console. The test AGI scripts included with Asterisk contain an example
! of this behavior.
! </para>
! </sect1>
! <sect1>
! <title>Language-specific AGI notes and examples</title>
! <para>
! Specific examples for languages can be found at
! <ulink url="http://home.cogeco.ca/~camstuff/agi.html" type="url">http://home.cogeco.ca/~camstuff/agi.html</ulink>.
! </para>
<sect2>
<title>C</title>
***************
*** 32,36 ****
<sect2>
<title>Perl</title>
! <para/>
</sect2>
<sect2>
--- 134,190 ----
<sect2>
<title>Perl</title>
! <para>
! Perl's propensity for data manipulation and quick scripting make
! it a very popular <!-- The most?-->choice for AGI scripting.
! To make Perl AGI programming even easier, James Golovich created
! Asterisk::AGI, a module designed for simplifying AGI interaction.
! Asterisk::AGI is available from the author's web page at
! <ulink url="http://asterisk.gnuinter.net/"type="http"></ulink>.
! </para>
! <para>
! Without using Asterisk::AGI, this is what a simple AGI script
! to tell a user their phone number would look like.
! <programlisting>
! #!/usr/bin/perl -w
!
! use strict;
!
! $|=1;
!
! #Get the initial data
! my %input;
! while(<STDIN>) {
! chomp;
! last unless length($_);
! if (/^agi_(\w+)\:\s+(.*)$/) {
! $input{$1} = $2;
! }
! }
!
! print "stream file the-number-is";
! print "say digits $input{callerid}";
! print "exec WaitMusicOnHold 2";
! print "hangup";
! </programlisting>
! Note the <varname>$|</varname> set to force a buffer flush after
! each print.
! </para>
! <para>
! Using Asterisk::AGI, we can simplify the previous script a bit:
! <programlisting>
! #!/usr/bin/perl -w
!
! use strict;
! use Asterisk::AGI;
!
! $AGI = new Asterisk::AGI;
! my %input = $AGI->ReadParse(); #Read in the initial data
!
! $AGI->stream_file('the-number-is');
! $AGI->say_digits($input{callerid});
! $AGI->exec('WaitMusicOnHold','2');
! $AGI->hangup();
! </programlisting>
! </para>
</sect2>
<sect2>
***************
*** 43,45 ****
--- 197,203 ----
</sect2>
</sect1>
+ <sect1>
+ <title>EAGI</title>
+ <para/>
+ </sect1>
</chapter>
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum