[Asterisk-doc] docs advanced-config.xml,1.1,1.2 agi.xml,1.1,1.2
blitzrage
asterisk-doc@lists.digium.com
Sat, 20 Mar 2004 17:32:17 +0000
Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21424/docs
Modified Files:
advanced-config.xml agi.xml
Log Message:
blitzrage:
- 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>