Sipcat DeveloperGuide 1.0

LINUGEN SIPCAT VOICE OVER IP SOFTWARE
Developer Guide
Sipcat Deve loper Gu ide
Sipcat Developer Guide
V 1.0 Copyright 2006 - 2007 Linugen All rights reserved. Linugen bvba Lange Koepoortstraat 41/11 2000 Antwerpen Belgium T: + 32 70 66 05 79 F: + 32 3 747 47 49 hello@linugen.com www.linugen.com
2006 - 2007 Linugen
Ta ble of Contents
Introduction
About This Document
7
8
API Overview
XML AMI
9
9 12
Scenarios
Creating a new user Listing available groups Making a call Listing all calls Transferring a call Hanging up a call
13
13 15 16 17 18 18
Code Examples
C# Perl PHP
19
19 21 22
XML Feature Codes XML Payloads

Users Groups Extensions Trunks Inbound Routing Outbound Routing Call Groups
2006 - 2007 Linugen
23 25
25 26 26 27 27 28 28
3
Call Queues Conferences Interactive Voice Response Address Book Prompts Music On Hold General Date and Time Network Telephony
28 29 29 30 30 30 30 31 31 32
XML Payload Types XML Action Types AMI Commands

AbsoluteTimeout ChangeMonitor Command Events ExtensionState Getvar Hangup IAXpeers ListCommands Logoff MailboxCount MailboxStatus Monitor Originate ParkedCalls Ping QueueAdd Queues
2006 - 2007 Linugen
33 34 35
35 35 35 35 36 36 36 36 36 37 37 37 37 37 38 38 38 38
4
QueueStatus Redirect SetCDRUserField Setvar SIPpeers Status StopMonitor
38 38 39 39 39 39 39
AMI Events
AgentCallbackLogin AgentCallbackLogoff AgentCalled AgentLogin AgentLogoff Alarm AlarmClear Cdr Dial ExtensionStatus Hangup Join Leave Link MeetmeJoin MeetmeLeave MessageWaiting Newcallerid Newchannel Newexten Newstate ParkedCall ParkedCallsComplete QueueMember QueueMemberAdded
2006 - 2007 Linugen
40
40 40 40 41 41 41 41 41 42 42 42 42 43 43 43 43 43 44 44 44 44 45 45 45 45
5
QueueParams QueueStatusEnd Reload Rename Shutdown Status StatusComplete Unlink ZapShowChannels ZapShowChannelsComplete
46 46 46 46 46 47 47 47 47 47
2006 - 2007 Linugen
CHAPTER
1
Intr oduction
While Sipcat offers a powerful web management interface, this may not always provide the required functionality in terms of interoperability with your existing software applications. Thats why Sipcat includes an advanced Application Programming Interface (API) that allows you to integrate Sipcat in your existing software environment. Sipcats API is based on the eXtensible Markup Language (XML) which allows transparent integration with any kind of platform regardless of operating system or programming language. The API offers all the functionalities found in the web management interface. Additionally the API allows direct interaction with the underlying Asterisk Manager Interface (AMI), which is not possible using the web management interface. Using the Application Programming Interface you can integrate Sipcat in existing administrative processes such as user creation. For example, when creating a new user in your existing environment, you could automatically send an XML command to Sipcat, which would immediately create the user in Sipcat using the same user credentials. This allows you to save a substantial amount of time and avoids repetitive administrative processes. On the other hand, Sipcats core integration allows you for example to transfer calls using simple XML commands or pick up caller ID information on incoming calls. These features can be easily integrated in your existing ERP or CRM applications using the standards based XML commands provided by the Sipcat API.
2006 - 2007 Linugen
About This Document

This document contains complete information on using Sipcats API to integrate it with your existing software applications. It also includes scenarios and code examples for clarification. Please read it carefully before using the API. To obtain the latest version of this document, or to get access to our knowledgebase, FAQs and support system, please visit: http://www.sipcat.com/support/ For more help regarding this or other issues, you can also visit our forum: http://www.sipcat.com/support/forum/
2006 - 2007 Linugen
CHAPTER
2
API O ver view
This chapter will provide a basic overview of the Application Programming Interface (API). It will cover the different available technologies and their uses.
XML
Sipcat provides access to its management interface via the eXtensible Markup Language (XML). This allows you to perform virtually every possible action available through the web interface, from within your own software application, effectively eliminating the need to access the management interface using your web browser. XML messages can be sent to the Sipcat system, using the standard HTTP port (80) or the secure HTTP/S port (443). XML messages should be posted to the following URL: http://10.0.0.1/sipcat_xml.php, replacing 10.0.0.1 by the actual IP address of the Sipcat system. They can be sent using any programming language on any platform. Later in this document we will provide some code examples. A basic XML request message looks like this:
<?xml version="1.0"?> <sipxml> <type> ... </type> <username> ... </username> <password> ... </password> <request> <instance> <node> ... </node> <feature> ... </feature> <method> ... </method> <payload> ... </payload> </instance> </request> </sipxml>
Well start by analyzing each line of the XML message above to give you a clear impression of how each message is structured.
2006 - 2007 Linugen
<?xml version="1.0"?>
This tag indicates the XML version used and should always be included. There is no closing tag for this element.
<sipxml> ... </sipxml>
Every message to the Sipcat system should start and end with this tag. Anything outside of the sipxml tag will be disregarded.
<type> ... </type>
The type tag indicates the kind of XML message you are sending. recognizes five different message types: ACTN Perform a certain task on the Sipcat system. AUTH Authenticate a user or a node. CONF Configure a Sipcat feature. IDENT Identify a Sipcat machine. INFO Request information about a Sipcat feature. RESP Sipcats response to the sent XML message.
<username> ... </username> <password> ... </password>
Sipcat
Every message to the Sipcat system should be authenticated by a username and password. The user should have at least privileges to perform Actions.
<request> ... </request>
After specifying the message type and authenticating, the actual request can be sent. The complete request should be contained between request tags.
<instance> ... </instance>
A request can contain multiple instances of the same type. You cannot, however, mix different message types in a single request.
<node> ... </node>
The node tag indicates the Sipcat machine on which you would like to perform your action. This has to be the hostname of the machine as defined in the management interface in the Configuration > Network menu.
<feature> ... </feature>
The feature tag specifies which feature you would like to modify or perform an action on. You will find a complete list of all the feature codes in Appendix I.
<method> ... </method>
The method tag is only used for CONF message types, and specifies what type of configuration you would like to perform. Valid methods are: 1 Add feature 2 Edit feature 3 Delete feature 4 View feature
<payload> ... </payload>
2006 - 2007 Linugen
10
The payload contains the actual information regarding the action you would like to perform and is dependent on the type of the message. Each XML request will receive a response from the Sipcat system. A XML response message looks like this:
<?xml version="1.0"?> <sipxml> <type>RESP</type> <status> ... </status> <result> ... </result> </sipxml>
A response is formatted the same way as a XML request message, its content is contained between sipxml tags and can be identified by the RESP message type.
<status> ... </status>
The status element contains an error code providing more information about your request. Valid status values are: 0 General error. 1 Successful. 2 Partial error. 3 Unauthorized 4 Invalid. 5 Post error. 6 Unknown. 7 SQL error. 8 Write error. 9 Asterisk error. 10 Remote error. 11 Inconsistent error. 12 Insecure error.
<result> ... </result>
The result element contains additional freeform text in the case of an error response or the requested results in case of a success response.
XML Authentication
Any user defined in the web interface can access the XML API as long as the user is at least granted the Actions privilege. Users will only be allowed to perform modifications to certain features if the corresponding privilege has been set in the web interface. For more information on setting privileges please refer to the Administrator Guide.
2006 - 2007 Linugen
11
AMI
The Asterisk Manager Interface (AMI) provides direct access to the underlying Asterisk PBX core. This is useful for receiving real-time events or performing actions on ongoing calls. The AMI can be accessed by opening a TCP/IP session to the AMI port (5038). This can be tested manually by opening a Telnet session to the specified port. A simple "key: value" line-based protocol is utilized for communication between the connecting client and the Asterisk PBX core. Lines are terminated using the Carriage Return / Line Feed combination. A basic authentication message looks like this:
Action: login Username: admin Secret: MyPassword
Asterisk may also generate event messages when certain events occur. The event below is generated when two voice channels are linked and communications commence.
Event: Link Channel1: SIP/101-3f3f Channel2: Zap/2-1 Uniqueid1: 1094154427.10 Uniqueid2: 1094154427.11
For a complete list of available AMI commands, please refer to Appendix V; for AMI events, please refer to Appendix VI.
AMI Authentication
Access to the AMI is governed by Asterisks manager configuration file. This file can be modified locally at the console or by connecting remotely using SSH. The manager configuration file is located in /etc/asterisk/manager.conf . To allow external access to the AMI, add a paragraph to the manager.conf file like this, replacing the network/subnet parameters as appropriate:
[admin] secret = MyPassword deny = 0.0.0.0/0.0.0.0 permit = 192.168.0.0/255.255.0.0 read = system,call,log,verbose,command,agent,user write = system,call,log,verbose,command,agent,user
2006 - 2007 Linugen
12
CHAPTER
3
Scenarios
This chapter presents some scenarios where the Application Programming Interface can be used. Both the XML and AMI interfaces will be discussed here.
Creating a new user

The following XML request will create a new user on the system with the parameters specified within the payload of the XML message. The user will also receive full access permissions to modify users and extensions.
<?xml version="1.0"?> <sipxml> <type>CONF</type> <username>admin</username> <password>MyPassword</password> <request> <instance> <node>demo.sipcat.com</node> <feature>f1aa</feature> <method>1</method> <payload> <firstname>John</firstname> <lastname>Doe</lastname> <username>jdoe</username> <password>sdfwer234</password> <pin>1234</pin> <language>en</language> <email>jdoe@sipcat.com</email> <mobile_phone>0475859505</mobile_phone> <home_phone>035551234</home_phone> <users>2</users> <extensions>2</extensions> </payload> </instance> </request> </sipxml>
2006 - 2007 Linugen
13
The response message indicates that the user was successfully created (Status = 1) and displays the request. Additional instances indicate that other actions where performed. In this case building the configuration (a0CA) and writing the TFTP provisioning file (a0q). For more information on the different action types, please refer to Appendix IV.
<?xml version="1.0"?> <sipxml> <type>RESP</type> <status>1</status> <result> <instance> <result>1</result> <node>demo.sipcat.com</node> <feature>f1aa</feature> <payload> <firstname>John</firstname> <lastname>Doe</lastname> <username>jdoe</username> <password>sdfwer234</password> <pin>1234</pin> <language>en</language> <email>jdoe@sipcat.com</email> <mobile_phone>0475859505</mobile_phone> <home_phone>035551234</home_phone> <users>2</users> <extensions>2</extensions> </payload> <method>1</method> </instance> <instance> <actn_type>a0CA</act_type> <status>1</status> </instance> <instance> <actn_type>a0q</actn_type> <status>1</status> </instance> </result> </sipxml>
2006 - 2007 Linugen
14
Listing available groups

The following XML request will list all groups available on the system. Note that the XML type is INFO instead of CONF as in the previous example. The payload type indicates what information you are requesting. A complete list of payload types is available in Appendix III.
<?xml version="1.0"?> <sipxml> <type>INFO</type> <username>admin</username> <password>MyPassword</password> <request> <instance> <node>demo.sipcat.com</node> <feature>f1a</feature> <payload>2</payload> </instance> </request> </sipxml>
The response message contains a data block with two instances listing the available groups. With each group the permissions that apply to it are listed as well.
<?xml version="1.0"?> <sipxml> <type>RESP</type> <status>1</status> <result> <instance> <data> <instance> <featureset>f1a:2</featureset> <id>1</id> <name>Administrators</name> <users>2</users> <extensions>2</extensions> <trunks>2</trunks> <routing>2</routing> <call_groups>2</call_groups> <call_queues>2</call_queues> <conferences>2</conferences> <ivrs>2</ivrs> <speeddials>2</speeddials> <fax>2</fax> <recordings>2</recordings> <general>2</general> <date_time>2</date_time> <network>2</network> <telephony>2</telephony> <actions>2</actions> <license>2</license>
2006 - 2007 Linugen
15
<updates>2</updates> <backup>2</backup> <status>2</status> <reports>2</reports> <destinations>1;4</destinations> </instance> <instance> <featureset>f1a:2</featureset> <id>2</id> <name>Users</name> <users>0</users> <extensions>0</extensions> <trunks>0</trunks> <routing>0</routing> <call_groups>0</call_groups> <call_queues>0</call_queues> <conferences>0</conferences> <ivrs>0</ivrs> <speeddials>0</speeddials> <fax>0</fax> <recordings>0</recordings> <general>0</general> <date_time>0</date_time> <network>0</network> <telephony>0</telephony> <actions>0</actions> <license>0</license> <updates>0</updates> <backup>0</backup> <status>0</status> <reports>0</reports> <destinations></destinations> </instance> </data> </instance> </result> </sipxml>
Making a call
The following XML request will generate a call from extension 1000 to phone number 035551234. Note that the XML type is ACTN instead of INFO as in the previous example. The fm feature indicates that this is an AMI command. This means that originating a call can also be achieved using the AMI instead of XML API.
2006 - 2007 Linugen
16
<?xml version="1.0"?> <sipxml> <type>ACTN</type> <username>admin</username> <password>MyPassword</password> <request> <instance> <node>demo.sipcat.com</node> <feature>fm</feature> <payload>originate;1000;035551234</payload> </instance> </request> </sipxml>
The response indicates success (Status = 1) and puts the original AMI response in the data block.
<?xml version="1.0"?> <sipxml> <type>RESP</type> <status>1</status> <result> <instance><instance> <data>Response: Success Message: Originate successfully queued </data> </instance></instance> </result> </sipxml>
Listing all calls

The following AMI request will list all active channels.
Action: Command Command: show channels
The response provides a list of active channels, their location, state and application information.
Response: Follows Privilege: Command Channel SIP/83.217.68.200-08 SIP/1000-085c4770 2 active channels 1 active call --END COMMAND--
Location (None) s@macro-dial-out:9
State Up Up
... ... ...
2006 - 2007 Linugen
17
Transferring a call
The following AMI request will transfer the call on extension 1000 to extension 4000. The Channel information is gathered from the show channels command in the previous example.
Action: Redirect Channel: SIP/1000-085c4770 Context: from-internal Exten: 4000 Priority: 1
The response indicates that the transfer was successful.

Response: Success Message: Redirect successful
Hanging up a call
The following AMI request will hang up the call on extension 1000.
Action: Hangup Channel: SIP/1000-085c4770
The response indicates that the channel was successfully hung up.
Response: Success Message: Channel Hungup
2006 - 2007 Linugen
18
CHAPTER
4
Code Examples
This chapter provides code examples for a number of different programming languages. These indicate how you can communicate with the different APIs available in Sipcat.
C#
AMI
using using using using using System; System.Net; System.Net.Sockets; System.Text.RegularExpressions; System.Text;
namespace AsteriskPrototype { class AppConsole { [STAThread] static void Main(string[] args) { Console.WriteLine("Sipcat AMI Test:\n"); // Connect to the asterisk server. Socket clientSocket = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp); IPEndPoint serverEndPoint = new IPEndPoint(IPAddress.Parse("192.168.0.10"), 5038); clientSocket.Connect(serverEndPoint); // Login to the server clientSocket.Send(Encoding.ASCII.GetBytes("Action: Login\r\nUsername: admin\r\nSecret: admin\r\nActionID: 1\r\n\r\n")); int bytesRead = 0;
2006 - 2007 Linugen
19
do { byte[] buffer = new byte[1024]; bytesRead = clientSocket.Receive(buffer); string response = Encoding.ASCII.GetString(buffer, 0, bytesRead); Console.WriteLine(response); if(Regex.Match(response, "Message: Authentication accepted", RegexOptions.IgnoreCase).Success) { // Send a ping request the Sipcat server clientSocket.Send(Encoding.ASCII.GetBytes("Action: Ping\r\nActionID: 2\r\n\r\n")); } }while(bytesRead != 0); Console.WriteLine("Connection to server lost."); Console.ReadLine(); } } }
XML
private string sendXML(string URI, string XML) { System.Net.WebRequest req = System.Net.WebRequest.Create(URI); req.Proxy = new System.Net.WebProxy(ProxyString, true); req.ContentType = "application/x-www-form-urlencoded"; req.Method = "POST"; byte [] bytes = System.Text.Encoding.ASCII.GetBytes(XML); req.ContentLength = bytes.Length; System.IO.Stream os = req.GetRequestStream (); os.Write (bytes, 0, bytes.Length); os.Close (); System.Net.WebResponse resp = req.GetResponse(); if (resp== null) return null; System.IO.StreamReader sr = new System.IO.StreamReader(resp.GetResponseStream()); return sr.ReadToEnd().Trim(); }
2006 - 2007 Linugen
20
Perl
AMI
#!/usr/bin/perl -w use Asterisk::AGI; use Net::Telnet (); $mgrUSERNAME='admin'; $mgrSECRET='admin'; $server_ip='192.168.0.10'; $tn = new Net::Telnet (Port => 5038, Prompt => '/.*[\$%#>] $/', Output_record_separator => '', Errmode => 'return'); #connect to manager and login $tn->open("$server_ip"); $tn->waitfor('/0\n$/'); $tn->print("Action: Login\nUsername: $mgrUSERNAME\nSecret: $mgrSECRET\n\n"); $tn->waitfor('/Authentication accepted\n\n/'); #issue command $tn->print("Action: command\nCommand: $command\n\n\n"); $tn->waitfor('/Response: Follows\n/'); ($schannels)=$tn->waitfor('/--END COMMAND--/') or die "Unable to get channels", $tn->lastline; # wait for asterisk to process $tn->print("Action: Logoff\n\n"); return $schannels;
XML
#!/usr/bin/perl -w use LWP::UserAgent; use HTTP::Request::Common; my $userAgent = LWP::UserAgent->new(agent => 'My Program'); my $response = $userAgent->request(POST 'http://192.168.0.10/sipcat_xml.php', Content_Type => application/x-www-form-urlencoded, Content => $message); print $response->error_as_HTML unless $response->is_success; print $response->as_string;
2006 - 2007 Linugen
21
PHP
AMI
require_once("phpagi.php"); require_once("phpagi-asmanager.php"); $msg_login = "Action: login\r\n". "Username: sipcat\r\n". "Secret: sipcat\r\n". "Events: on\r\n\r\n"; $msg_logoff = "Action: logoff\r\n\r\n"; $mancon = new AGI_AsteriskManager(); if($mancon->connect("192.168.0.10", "sipcat", "sipcat")) { $input_command = $mancon->command($command); $mancon->disconnect(); } return $input_command['data'];
XML
function sendXML($host, $xml) { $xml_length = strlen($xml); $xml_header = "POST /sipcat_xml.php HTTP/1.0\n". "Host: $host\n". "User-Agent: My Program\n". "Content-Type: application/x-www-form-urlencoded\n". "Content-Length: $xml_length\n\n". "$xml\n"; $fp = @fsockopen("ssl://$host", 443, $errno, $errstr, 10); @socket_set_timeout($fp, 10); @stream_set_timeout($fp, 10); if(!$fp) { if($errno == 0) { // Fatal error: Unable to connect to host } else { // Fatal error: $errstr and $errno } } else { @fputs($fp, $xml_header); $result = ''; while(!feof($fp)) { $result .= @fread($fp, 8192); } @fclose($fp); } $result = join("", explode("\n", $result)); return $result; }
2006 - 2007 Linugen
22
APPENDIX
I
XML Fe ature Codes
Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Configuration Configuration Configuration Configuration Configuration Configuration Configuration Configuration Configuration > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Users Users Users Extensions Trunks Routing Routing Routing Call Groups Call Queues Conferences IVRs Fax Recordings Recordings Recordings Recordings General General General General General Address Book Date / Time Network Telephony Actions Updates Cluster License Backup > > Users Groups
f1 f1a f1aa f1ab f1b f1c f1d f1da f1db f1e f1f f1g f1h f1i f1j f1ja f1jb f1jc f1k f1ka f1kb f1kc f1kd f1l f2 f2a f2b f2c f2d f2e f2f f2h f2i
> >
Inbound Outbound
> > > > > > >
Prompts Music on Hold Recordings Services Destinations Timezones Phone Types
2006 - 2007 Linugen
23
Status Reports Reports Reports Reports Reports Reports Help Asterisk Manager Debug Debug Debug Operator Panel > > > General XML > > > > > Search Daily Weekly Monthly Logging
f3 f4 f4a f4b f4c f4d f4e f5 fm fd0 fd0a fd0b op
2006 - 2007 Linugen
24
APPENDIX
II
XML Payloads
Users
<id> <firstname> <lastname> <username> <password> <pin> <language> <email> <mobile_phone> <home_phone> <other_phone> <group_id> </id> </firstname> </lastname> </username> </password> </pin> </language> </email> </mobile_phone> </home_phone> </other_phone> </group_id>
Privileges
<users> <extensions> <trunks> <routing> <call_groups> <call_queues> <conferences> <ivrs> <speeddials> <fax> <recordings> <general> <date_time> <network> <actions> <telephony> <updates> <license> <backup> <status> <reports> <destinations> </users> </extensions> </trunks> </routing> </call_groups> </call_queues> </conferences> </ivrs> </speeddials> </fax> </recordings> </general> </date_time> </network> </actions> </telephony> </updates> </license> </backup> </status> </reports> </destinations>
2006 - 2007 Linugen
25
Groups
<id> <name> </id> </name>
Privileges
<users> <extensions> <trunks> <routing> <call_groups> <call_queues> <conferences> <ivrs> <speeddials> <fax> <recordings> <general> <date_time> <network> <actions> <telephony> <updates> <license> <backup> <status> <reports> <destinations> </users> </extensions> </trunks> </routing> </call_groups> </call_queues> </conferences> </ivrs> </speeddials> </fax> </recordings> </general> </date_time> </network> </actions> </telephony> </updates> </license> </backup> </status> </reports> </destinations>
Extensions
<id> <name> <label> <line_nr> <phone_type> <extension_type> <mac> <technology> <user> <rec_in> <rec_out> <status> <visible> </id> </name> </label> </line_nr> </phone_type> </extension_type> </mac> </technology> </user> </rec_in> </rec_out> </status> </visible>
Voicemail
<vm_enabled> <vm_email_attach> <vm_play_clid> <vm_play_env> <vm_play_next> <vm_delete_vm> </vm_enabled> </vm_email_attach> </vm_play_clid> </vm_play_env> </vm_play_next> </vm_delete_vm>
2006 - 2007 Linugen
26
Caller ID
<callerid> <outcallerid> </callerid> </outcallerid>
Failover
<failover_1> <failover_2> <failover_3> <failover_4> <failover_5> </failover_1> </failover_2> </failover_3> </failover_4> </failover_5>
Advanced
<nat> <host> <voice_compression> <ringtime> <dtmfmode> </nat> </host> </voice_compression> </ringtime> </dtmfmode>
Features
<dnd> <cw> <cf> <cfb> </dnd> </cw> </cf> </cfb>
Trunks
<id> <name> <protocol> <channels> <dial_prefix> <status> <host> <username> <password> <register> </id> </name> </protocol> </channels> </dial_prefix> </status> </host> </username> </password> </register>
Advanced
<voice_compression> <dtmfmode> <timeout> <callerid> <clidusage> </voice_compression> </dtmfmode> </timeout> </callerid> </clidusage>
Inbound Routing
<id> <priority> <name> <event> <timezones> <action>
2006 - 2007 Linugen
</id> </priority> </name> </event> </timezones> </action>

27
Outbound Routing
<id> <priority> <name> <prefix> <destinations> <timezones> <trunk_sequence> </id> </priority> </name> </prefix> </destinations> </timezones> </trunk_sequence>
Call Groups
<id> <name> <extension> <extensions> <group> <clidprefix> <ringtime> <rec_in> <status> </id> </name> </extension> </extensions> </group> </clidprefix> </ringtime> </rec_in> </status>
Failover
Call Queues
<id> <name> <extension> <extensions> <group> <trunks> <clidprefix> <pin> <status> </id> </name> </extension> </extensions> </group> </trunks> </clidprefix> </pin> </status>
Recordings
<greeting_user> <greeting_member> <musiconhold> <announce> <queue_youarenext> <queue_thereare> <queue_callswaiting> <queue_holdtime> <queue_minutes> <queue_seconds> <queue_thankyou>
2006 - 2007 Linugen
</greeting_user> </greeting_member> </musiconhold> </announce> </queue_youarenext> </queue_thereare> </queue_callswaiting> </queue_holdtime> </queue_minutes> </queue_seconds> </queue_thankyou>
28
<queue_lessthan> <queue_reporthold> <periodic_announce>
</queue_lessthan> </queue_reporthold> </periodic_announce>
Advanced
<strategy> <timeout> <retry> <weight> <wrapuptime> <maxlen> <announce_frequency> <periodic_announce_frequency> <announce_holdtime> <monitor> <joinempty> <reportholdtime> </strategy> </timeout> </retry> </weight> </wrapuptime> </maxlen> </announce_frequency> </periodic_announce_frequency> </announce_holdtime> </monitor> </joinempty> </reportholdtime>
Failover
Conferences
<id> <name> <extension> <pin> <admin_pin> <status> </id> </name> </extension> </pin> </admin_pin> </status>
Advanced
<options> </options>
Interactive Voice Response

<id> <name> <extension> <allow_local> <status> <digit_0> <digit_1> <digit_2> <digit_3> <digit_4> <digit_5> <digit_6> <digit_7> <digit_8> <digit_9>
2006 - 2007 Linugen
</id> </name> </extension> </allow_local> </status> </digit_0> </digit_1> </digit_2> </digit_3> </digit_4> </digit_5> </digit_6> </digit_7> </digit_8> </digit_9>
29
<digit_10> <digit_11>
</digit_10> </digit_11>
Failover
Advanced
<greeting> <timeout> </greeting> </timeout>
Address Book
<id> <extension> <destination> <name> <comment> </id> </extension> </destination> </name> </comment>
Prompts
<id> <name> <filename> <comment> </id> </name> </filename> </comment>
Music On Hold
<id> <name> <filename> <folder> <comment> </id> </name> </filename> </folder> </comment>
Folders
<id> <name> <comment> </id> </name> </comment>
General
<default_language> <emailvmbody> <emailfaxbody> <emailrecbody> <fromaddr>
2006 - 2007 Linugen
</default_language> </emailvmbody> </emailfaxbody> </emailrecbody> </fromaddr>

30
Services
<ext_voicemail> </ext_voicemail> <ext_dnd_enable> </ext_dnd_enable> <ext_dnd_disable> </ext_dnd_disable> <ext_call_forward_enable> </ext_call_forward_enable> <ext_call_forward_disable> </ext_call_forward_disable> <ext_call_forward_on_busy_enable></ext_call_forward_on_busy_enable> <ext_call_forward_on_busy_disable></ext_call_forward_on_busy_disable> <ext_call_waiting_enable> </ext_call_waiting_enable> <text_call_waiting_disable> </ext_call_waiting_disable> <start_callpark> </start_callpark> <ext_callpark> </ext_callpark> <ext_pickup> </ext_pickup> <ext_blindxfer> </ext_blindxfer> <ext_atxfer> </ext_atxfer> <ext_disconnect> </ext_disconnect> <ext_masspage> </ext_masspage> <ext_automon> </ext_automon> <parkinglot_size> </parkinglot_size> <ext_company_directory> </ext_company_directory> <ext_recordings> </ext_recordings> <start_extensions> </start_extensions> <start_callgroups> </start_callgroups> <start_callqueues> </start_callqueues> <start_conferences> </start_conferences> <start_ivrs> </start_ivrs> <start_speeddials> </start_speeddials>
Destinations
<id> <name> <prefix> <destination> </id> </name> </prefix> </destination>
Date and Time

<use_server> <server> <year> <month> <day> <hour> <minute> <dst> <location> </use_server> </server> </year> </month> </day> </hour> </minute> </dst> </location>
Network
<hostname> <use_server> <ip> <nat_ip> <netmask> <network> <broadcast>
2006 - 2007 Linugen
</hostname> </use_server> </ip> </nat_ip> </netmask> </network> </broadcast>

31
<gateway> <dns_1> <dns_2> <smtp>
</gateway> </dns_1> </dns_2> </smtp>
Telephony
<location> <switchtype> <nationalprefix> <internationalprefix> <echocancel> <echotraining> <card1> <card2> <card3> </location> </switchtype> </nationalprefix> </internationalprefix> </echocancel> </echotraining> </card1> </card2> </card3>
2006 - 2007 Linugen
32
APPENDIX
III
XML Payload Types
Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Management Configuration Configuration Configuration Configuration Configuration Configuration > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Users Users Extensions Extensions Trunks Routing Routing Call Groups Call Groups Call Queues Call Queues Conferences Conferences IVRs IVRs Address Book Address Book Recordings Recordings Recordings Fax General General General General General Date / Time All Network Telephony Telephony Updates License > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > All Users All Groups All Extensions Suggest Extension All Trunks All Inbound Routes All Outbound Routes All Call Groups Suggest Call Group All Call Queues Suggest Call Queue All Conferences Suggest Conference All IVRs Suggest IVR All Address Book Records Suggest Address Book Record All Prompts All Music On Hold All Recordings All Faxes All General All Phone Types All Services All Destinations All Time Zones All Date / Time All Network All Cards All Telephony All Updates All License
1 2 1 2 1 1 2 1 2 1 2 1 2 1 2 1 2 1 2 3 1 1 2 3 4 5 1 1 1 2 1 1
2006 - 2007 Linugen
33
APPENDIX
IV
XML Action Types
Build Configuration Build Dialplan Build Dialplan Services Build Dialplan Extensions Build Dialplan Call Groups Build Dialplan Call Queues Build Dialplan Conferences Build Dialplan IVRs Build Dialplan Inbound Routes Build Dialplan Outbound Routes Reload Asterisk Restart Asterisk Restart HTTPD Start Asterisk Stop Asterisk Shutdown Server Reboot Server Optimize Database Reload Network Restart Network Start Network Reset CDR Reset Logs Apply Network Apply Telephony Apply Date/Time Build TFTP Configuration Build SSL Certificate Factory Reset
a0CA a0ca a0cb a0cc a0cd a0ce a0cf a0cg a0ch a0ci a0d a0e a0eb a0f a0g a0h a0i a0j a0k a0l a0m a0n a0nb a0o a0ob a0p a0q a0r a0s
2006 - 2007 Linugen
34
APPENDIX
V
AMI Commands
AbsoluteTimeout
This will hangup a specified channel after a certain number of seconds, thereby actively ending the call.
Action: AbsoluteTimeout Channel: SIP/1000-085c4770 Timeout: 20
ChangeMonitor
Changes the filename of a recording occuring on a certain channel started by a previous Monitor command.
Action: AbsoluteTimeout Channel: SIP/1000-085c4770 Timeout: 20
Command
Runs an Asterisk console command.
Action: Command Command: show channels
Events
Enables or disables sending of events in the current AMI session.
Action: Events Eventmask: Off
2006 - 2007 Linugen
35
ExtensionState
Reports the extension state for given extension. If the extension has a hint, will use devicestate to check the status of the device connected to the extension.
Action: ExtensionState Context: from-internal Exten: SIP/1000
This will report one of the following statuses:

-1 0 1 4 8
Extension not found Idle In Use Unavailable Ringing
Getvar
Gets the value of a global or local channel variable.
Action: Getvar Channel: SIP/1000-085c4770 Variable: extension
Hangup
Hangs up the specified channel.
Action: Hangup Channel: SIP/1000-085c4770
IAXpeers
Shows the IAX peers and their status.
Action: IAXPeers
ListCommands
Lists the available AMI commands.
Action: ListCommands
2006 - 2007 Linugen
36
Logoff
Logs off the current manager session.
Action: Logoff
MailboxCount
Checks a voicemail account for new messages.
Action: MailboxCount Mailbox: 1000@from-internal
Returns the number of new and old messages.

Message: Mailbox Message Count Mailbox: 1000@from-internal NewMessages: 1 OldMessages: 2
MailboxStatus
Checks a voicemail account for status.
Action: MailboxStatus Mailbox: 1000@from-internal
Monitor
Records the audio on a specified channel.
Action: Monitor Channel: SIP/1000 File: myrecording Format: wav Mix: 1
Originate
Generates an outgoing call to a specified number.
Action: Originate Channel: SIP/1000 Context: from-internal Exten: 035551234 Priority: 1
2006 - 2007 Linugen
37
ParkedCalls
Lists all parked calls.
Action: ParkedCalls
Ping
Sollicits a Pong response to keep the manager connection open.
Action: Ping
QueueAdd
Add member to a queue.
Action: QueueAdd Queue: sales Interface: sip/1000 Penalty: 1 Paused: true
Queues
Returns configuration and statistical information about the existing queues. Action: Queues
QueueStatus
Checks statistical information about calls delivered to the existing queues, as well as the corresponding service level.
Action: QueueStatus
Redirect
Transfers a call to another extension.
Action: Redirect Channel: SIP/1000-085c4770 Context: from-internal Exten: 4000 Priority: 1
2006 - 2007 Linugen
38
SetCDRUserField
Sets the CDR user field to a certain value for further reference.
Action: SetCDRUserField Channel: SIP/1000-085c4770 UserField: myreference
Setvar
Sets a global or local channel variable.
Action: Setvar Channel: SIP/1000-085c4770 Variable: myvariable Value: myvalue
SIPpeers
Shows the SIP peers and their status.
Action: SIPpeers
Status
Lists the status of a channel.
Action: Status Channel: SIP/1000-085c4770
StopMonitor
Stops recording the audio on a specified channel.
Action: StopMonitor Channel: SIP/1000-085c4770
2006 - 2007 Linugen
39
APPENDIX
VI
AMI E vents
AgentCallbackLogin
This is triggered when an agent is succesfully logged in using AgentCallbackLogin.
Event: Agentcallbacklogin Agent: <agent> Loginchan: <loginchan> Uniqueid: <uniqueid>
AgentCallbackLogoff
This is triggered when an agent that previously logged in using AgentCallbackLogin is logged off.
Event: Agentcallbacklogoff Agent: <agent> Loginchan: <loginchan> Logintime: <logintime> Reason: Autologoff Uniqueid: <uniqueid>
AgentCalled
This is triggered when an agent is called. To enable AgentCalledEvents you have to set eventwhencalled = yes in queues.conf.
Event: AgentCalled AgentCalled: <channel> ChannelCalling: <channel> CallerID: <callerid> Context: <context> Extension: <extension> Priority: <priority>
2006 - 2007 Linugen
40
AgentLogin
This is triggered when an agent is successfully logged in using AgentLogin.
Event: Agentlogin Agent: <agent> Channel: <channel> Uniqueid: <uniqueid>
AgentLogoff
This is triggered when an agent that previously logged in using AgentLogin is logged off.
Event: Agentlogoff Agent: <agent> Logintime: <logintime> Uniqueid: <uniqueid>
Alarm
This is triggered when a Zap channel enters or changes alarm state.
Event: Alarm Alarm: <(Red|Yellow|Blue|No|Unknown)Alarm|Recovering|Loopback|Not Open|None> Channel: <channel>
AlarmClear
This is triggered when a Zap channel leaves alarm state.
Event: AlarmClear Channel: <channel>
Cdr
This is triggered when a call detail record is generated, usually at the end of a call. To enable CdrEvents you have to add enabled = yes to the general section in cdr_manager.conf.
Event: Cdr AccountCode: Source: Destination: DestinationContext: CallerID: Channel: DestinationChannel:
2006 - 2007 Linugen 41
LastApplication: LastData: StartTime: AnswerTime: EndTime: Duration: BillableSeconds: Disposition: AMAFlags: UniqueID: UserField:
Dial
This is triggered whenever a phone attempts to dial someone.
Event: Dial Privilege: call,all Source: Local/900@default-2dbf,2 Destination: SIP/900-4c21 CallerID: <unknown> CallerIDName: default SrcUniqueID: 1149161705.2 DestUniqueID: 1149161705.4
ExtensionStatus
This is triggered when the state of an extension changes.
Event: ExtensionStatus Exten: <ext> Context: <context> Status: <state>
Hangup
This is triggered when a channel is hung up.
Event: Hangup Channel: SIP/101-3f3f Uniqueid: 1094154427.10 Cause: 0
Join
This is triggered when a channel joines a queue.
Event: join Channel: <channel> CallerID: <callerid|unknown> Queue: <queuename>
2006 - 2007 Linugen 42
Position: <entryposition> Count: <queuemembercount>
Leave
This is triggered when a channel leaves a queue.
Event: leave Channel: <channel> Queue: <queuename> Count: <queuemembercount>
Link
This is triggered when two voice channels are linked together and voice data exchange commences. Several Link events may be seen for a single call. This can occur when Asterisk fails to setup a native bridge for the call. This is when Asterisk must sit between two telephones and perform CODEC conversion on their behalf.
Event: Link Channel1: SIP/101-3f3f Channel2: Zap/2-1 Uniqueid1: 1094154427.10 Uniqueid2: 1094154427.11
MeetmeJoin
This is triggered if a channel joins a meet me conference.
Event: MeetmeJoin Channel: <channel> Uniqueid: <uniqueid> Meetme: <meetme> Usernum: <usernum>
MeetmeLeave
This is triggered if a channel leaves a meet me conference.
Event: MeetmeLeave Channel: <channel> Uniqueid: <uniqueid> Meetme: <meetme> Usernum: <usernum>
MessageWaiting
This is triggered when someone leaves voicemail.
2006 - 2007 Linugen
43
Event: MessageWaiting Mailbox: <mailbox>@<context> Waiting: <count>
Newcallerid
This is triggered when the caller id of a channel changes.
Event: Newcallerid Channel: <channel> Callerid: <callerid> Uniqueid: <uniqueid>
Newchannel
This is triggered when a new channel is created.
Event: Newchannel Channel: SIP/101-3f3f State: Ring Callerid: 101 Uniqueid: 1094154427.10
Newexten
This is triggered when a channel is connected to a new extension.
Event: Newexten Channel: SIP/101-3f3f Context: local_extensions Extension: 917070 Priority: 2 Application: Dial AppData: Zap/G1/17070 Uniqueid: 1094154427.10
Newstate
This is triggered when the state of a channel has changed.
Event: Newstate Channel: Zap/2-1 State: Dialing Callerid: 101 Uniqueid: 1094154427.11
2006 - 2007 Linugen
44
ParkedCall
This is triggered when a channel is parked and in response to a ParkedCalls command.
Event: ParkedCall Exten: <parkexten> Channel: <channel> From: <from> Timeout: <timeout> CallerID: <callerid>
ParkedCallsComplete
This is triggered after all parked calls have been reported in response to a ParkedCalls command.
Event: ParkedCallsComplete
QueueMember
This is triggered in response to a QueueStatus command and contains information about a member of a queue.
Event: QueueMember Queue: sales Location: SIP/101 Membership: dynamic Penalty: 0 CallsTaken: 0 LastCall: 0
QueueMemberAdded
This is triggered when a queue member is added to a queue.
Event: QueueMemberAdded Privilege: agent,all Queue: testing Location: Agent/AgentId Membership: dynamic Penalty: 0 CallsTaken: 0 LastCall: 0 Status: 4 Paused: 1
2006 - 2007 Linugen
45
QueueParams
This is triggered in response to a QueueStatus command and contains the parameters of a queue.
Event: QueueParams Queue: sales Max: 0 Calls: 0 Holdtime: 0 Completed: 0 Abandoned: 0 ServiceLevel: 0 ServicelevelPerf: 0.0
QueueStatusEnd
This is triggered in response to a QueueStatus command and signifies the end of output.
Event: QueueStatusEnd
Reload
This is triggered when the reload console command is executed or the asterisk server is started.
Event: Reload Message: Reload Requested
Rename
This is triggered when the name of a channel is changed.
Event: Rename Oldname: <oldname> Newname: <newname> Uniqueid: <uniqueid>
Shutdown
This is triggered when the asterisk server is shut down or restarted.
Event: Shutdown Shutdown: <Uncleanly|Cleanly> Restart: <True|False>
2006 - 2007 Linugen
46
Status
This is triggered for each active channel in response to a Status command.
Event: Status Channel: Zap/2-1 CallerID: 101 Account: State: Up Link: SIP/101-5cf0 Uniqueid: 1094166088.26
StatusComplete
This is triggered after the state of all channels has been reported in response to a Status command.
Event: StatusComplete
Unlink
This is triggered when a link between two voice channels is discontinued, for example, just before call completion.
Event: Unlink Channel1: SIP/101-3f3f Channel2: Zap/2-1 Uniqueid1: 1094154427.10 Uniqueid2: 1094154427.11
ZapShowChannels
This is triggered in response to a ZapShowChannels command and shows the state of a zap channel.
Event: ZapShowChannels Channel: 2 Signalling: FXS Kewlstart Context: pstn_menu Alarm: No Alarm
ZapShowChannelsComplete
This is triggered after the state of all zap channels has been reported in response to a ZapShowChannelsAction.
Event: ZapShowChannelsComplete
2006 - 2007 Linugen
47

Sipcat DeveloperGuide 1.0

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Sipcat DeveloperGuide 1.0

Caricato da

Copyright:

Formati disponibili

LINUGEN SIPCAT VOICE OVER IP SOFTWARE

Sipcat Deve loper Gu ide

Sipcat Developer Guide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

XML Feature Codes XML Payloads

Sipcat Deve loper Gu ide

XML Payload Types XML Action Types AMI Commands

Sipcat Deve loper Gu ide

QueueStatus Redirect SetCDRUserField Setvar SIPpeers Status StopMonitor

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

About This Document

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

Creating a new user

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

Listing available groups

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

Listing all calls

Action: Command Command: show channels

Location (None) s@macro-dial-out:9

... ... ...

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

Action: Redirect Channel: SIP/1000-085c4770 Context: from-internal Exten: 4000 Priority: 1

The response indicates that the transfer was successful.

Action: Hangup Channel: SIP/1000-085c4770

Response: Success Message: Channel Hungup

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

> > > > > > >

Prompts Music on Hold Recordings Services Destinations Timezones Phone Types

2006 - 2007 Linugen

Sipcat Deve loper Gu ide

f3 f4 f4a f4b f4c f4d f4e f5 fm fd0 fd0a fd0b op

2006 - 2007 Linugen