Posted: Sat Feb 21, 2004 5:31 am Post subject: [Asterisk-doc] New Docs!
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.
<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.
---
Quote:
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.
---
Quote:
language, just like CGI scripts.
26,27c28,129
< <title>AGI examples in various languages</title>
< <para/>
---
Quote:
<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/>
---
Quote:
<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
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