[Asterisk-doc] New Docs!
Nicholas Bachmann
asterisk-doc@lists.digium.com
Sat, 21 Feb 2004 00:31:56 -0500
This is a multi-part message in MIME format.
--------------090903070401050101060105
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Hi folks-
Its not a whole lot, but I wrote some more docs. A `cvs diff` is
attached. I wrote a section about .call files/auto dialout, but was
wondering if instead of "Advanced Configuration," where I put it, it
belongs in the AGI chapter (perhaps renamed to "Asterisk Scripting" or
something like that?). I also got a bunch of AGI stuff written down,
but there's a lot more to do in that chapter.
Anyway, enjoy!
Nick
--------------090903070401050101060105
Content-Type: text/plain;
name="diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="diff"
Index: advanced-config.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/advanced-config.xml,v
retrieving revision 1.1
diff -r1.1 advanced-config.xml
642a643,754
> <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='3' 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/>
> <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>
Index: agi.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/agi.xml,v
retrieving revision 1.1
diff -r1.1 agi.xml
17c17,19
< STDIN, and your script passes information back via STDOUT.
---
> 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.
19c21
< language.
---
> language, just like CGI scripts.
26,27c28,129
< <title>AGI examples in various languages</title>
< <para/>
---
> <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"></ulink>.
> </para>
34c136,188
< <para/>
---
> <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>
43a198,201
> </sect1>
> <sect1>
> <title>EAGI</title>
> <para/>
--------------090903070401050101060105--