Sipcat-DeveloperGuide-1.0

LINUGEN

SIPCAT VOICE OVER IP SOFTWARE

Developer Guide

Sipcat Developer Guide

© 2006 - 2007 Linugen 2


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 [email protected] www.linugen.com


© 2006 - 2007 Linugen 3

Table of Contents

Introduction 7

About This Document 8

API Overview 9

XML 9 AMI 12

Scenarios 13

Creating a new user 13 Listing available groups 15 Making a call 16 Listing all calls 17 Transferring a call 18 Hanging up a call 18

Code Examples 19

C# 19 Perl 21 PHP 22

XML Feature Codes 23

XML Payloads 25

Users 25 Groups 26 Extensions 26 Trunks 27 Inbound Routing 27 Outbound Routing 28 Call Groups 28


© 2006 - 2007 Linugen 4

Call Queues 28 Conferences 29 Interactive Voice Response 29 Address Book 30 Prompts 30 Music On Hold 30 General 30 Date and Time 31 Network 31 Telephony 32

XML Payload Types 33

XML Action Types 34

AMI Commands 35

AbsoluteTimeout 35 ChangeMonitor 35 Command 35 Events 35 ExtensionState 36 Getvar 36 Hangup 36 IAXpeers 36 ListCommands 36 Logoff 37 MailboxCount 37 MailboxStatus 37 Monitor 37 Originate 37 ParkedCalls 38 Ping 38 QueueAdd 38 Queues 38


© 2006 - 2007 Linugen 5

QueueStatus 38 Redirect 38 SetCDRUserField 39 Setvar 39 SIPpeers 39 Status 39 StopMonitor 39

AMI Events 40

AgentCallbackLogin 40 AgentCallbackLogoff 40 AgentCalled 40 AgentLogin 41 AgentLogoff 41 Alarm 41 AlarmClear 41 Cdr 41 Dial 42 ExtensionStatus 42 Hangup 42 Join 42 Leave 43 Link 43 MeetmeJoin 43 MeetmeLeave 43 MessageWaiting 43 Newcallerid 44 Newchannel 44 Newexten 44 Newstate 44 ParkedCall 45 ParkedCallsComplete 45 QueueMember 45 QueueMemberAdded 45


© 2006 - 2007 Linugen 6

QueueParams 46 QueueStatusEnd 46 Reload 46 Rename 46 Shutdown 46 Status 47 StatusComplete 47 Unlink 47 ZapShowChannels 47 ZapShowChannelsComplete 47


© 2006 - 2007 Linugen 7

Introduction

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. That’s why Sipcat includes an advanced Application Programming Interface (API) that allows you to integrate Sipcat in your existing software environment. Sipcat’s 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, Sipcat’s 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.

CHAPTER

1


© 2006 - 2007 Linugen 8

About This Document

This document contains complete information on using Sipcat’s 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, FAQ’s 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 9

API Overview

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>

We’ll start by analyzing each line of the XML message above to give you a clear impression of how each message is structured.

CHAPTER

2


© 2006 - 2007 Linugen 10

• <?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. Sipcat 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 Sipcat’s response to the sent XML message.

• <username> ... </username> <password> ... </password> 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 11

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 12

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 Asterisk’s 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 13

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.

CHAPTER

3

<?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>[email protected]</email> <mobile_phone>0475859505</mobile_phone> <home_phone>035551234</home_phone> <users>2</users> <extensions>2</extensions>

</payload> </instance>

</request> </sipxml>


© 2006 - 2007 Linugen 14

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>[email protected]</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 15

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.

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>INFO</type> <username>admin</username> <password>MyPassword</password> <request> <instance> <node>demo.sipcat.com</node> <feature>f1a</feature> <payload>2</payload>

</instance> </request> </sipxml>

<?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 16

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.

<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>


© 2006 - 2007 Linugen 17

The response indicates success (Status = 1) and puts the original AMI response in the data block.

Listing all calls

The following AMI request will list all active channels. The response provides a list of active channels, their location, state and application information.

<?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>

<?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>

Action: Command Command: show channels

Response: Follows Privilege: Command Channel Location State ... SIP/83.217.68.200-08 (None) Up ... SIP/1000-085c4770 s@macro-dial-out:9 Up ... 2 active channels 1 active call --END COMMAND--


© 2006 - 2007 Linugen 18

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. The response indicates that the transfer was successful.

Hanging up a call

The following AMI request will hang up the call on extension 1000. The response indicates that the channel was successfully hung up.

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

Response: Success Message: Redirect successful

Action: Hangup Channel: SIP/1000-085c4770

Response: Success Message: Channel Hungup


© 2006 - 2007 Linugen 19

Code Examples

This chapter provides code examples for a number of different programming languages. These indicate how you can communicate with the different API’s available in Sipcat.

C#

AMI using System; using System.Net; using System.Net.Sockets; using System.Text.RegularExpressions; using 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;

CHAPTER

4


© 2006 - 2007 Linugen 20

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 21

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 22

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 23

XML Feature Codes

Management f1 Management > Users f1a Management > Users > Users f1aa Management > Users > Groups f1ab Management > Extensions f1b Management > Trunks f1c Management > Routing f1d Management > Routing > Inbound f1da Management > Routing > Outbound f1db Management > Call Groups f1e Management > Call Queues f1f Management > Conferences f1g Management > IVRs f1h Management > Fax f1i Management > Recordings f1j Management > Recordings > Prompts f1ja Management > Recordings > Music on Hold f1jb Management > Recordings > Recordings f1jc Management > General f1k Management > General > Services f1ka Management > General > Destinations f1kb Management > General > Timezones f1kc Management > General > Phone Types f1kd Management > Address Book f1l Configuration f2 Configuration > Date / Time f2a Configuration > Network f2b Configuration > Telephony f2c Configuration > Actions f2d Configuration > Updates f2e Configuration > Cluster f2f Configuration > License f2h Configuration > Backup f2i

APPENDIX

I


© 2006 - 2007 Linugen 24

Status f3 Reports f4 Reports > Search f4a Reports > Daily f4b Reports > Weekly f4c Reports > Monthly f4d Reports > Logging f4e Help f5 Asterisk Manager fm Debug > fd0 Debug > General fd0a Debug > XML fd0b Operator Panel op


© 2006 - 2007 Linugen 25

XML Payloads

Users

<id> </id> <firstname> </firstname> <lastname> </lastname> <username> </username> <password> </password> <pin> </pin> <language> </language> <email> </email> <mobile_phone> </mobile_phone> <home_phone> </home_phone> <other_phone> </other_phone> <group_id> </group_id>

Privileges <users> </users> <extensions> </extensions> <trunks> </trunks> <routing> </routing> <call_groups> </call_groups> <call_queues> </call_queues> <conferences> </conferences> <ivrs> </ivrs> <speeddials> </speeddials> <fax> </fax> <recordings> </recordings> <general> </general> <date_time> </date_time> <network> </network> <actions> </actions> <telephony> </telephony> <updates> </updates> <license> </license> <backup> </backup> <status> </status> <reports> </reports> <destinations> </destinations>

APPENDIX

II


© 2006 - 2007 Linugen 26

Groups

<id> </id> <name> </name>

Privileges <users> </users> <extensions> </extensions> <trunks> </trunks> <routing> </routing> <call_groups> </call_groups> <call_queues> </call_queues> <conferences> </conferences> <ivrs> </ivrs> <speeddials> </speeddials> <fax> </fax> <recordings> </recordings> <general> </general> <date_time> </date_time> <network> </network> <actions> </actions> <telephony> </telephony> <updates> </updates> <license> </license> <backup> </backup> <status> </status> <reports> </reports> <destinations> </destinations>

Extensions

<id> </id> <name> </name> <label> </label> <line_nr> </line_nr> <phone_type> </phone_type> <extension_type> </extension_type> <mac> </mac> <technology> </technology> <user> </user> <rec_in> </rec_in> <rec_out> </rec_out> <status> </status> <visible> </visible>

Voicemail <vm_enabled> </vm_enabled> <vm_email_attach> </vm_email_attach> <vm_play_clid> </vm_play_clid> <vm_play_env> </vm_play_env> <vm_play_next> </vm_play_next> <vm_delete_vm> </vm_delete_vm>


© 2006 - 2007 Linugen 27

Caller ID <callerid> </callerid> <outcallerid> </outcallerid>

Failover <failover_1> </failover_1> <failover_2> </failover_2> <failover_3> </failover_3> <failover_4> </failover_4> <failover_5> </failover_5>

Advanced <nat> </nat> <host> </host> <voice_compression> </voice_compression> <ringtime> </ringtime> <dtmfmode> </dtmfmode>

Features <dnd> </dnd> <cw> </cw> <cf> </cf> <cfb> </cfb>

Trunks

<id> </id> <name> </name> <protocol> </protocol> <channels> </channels> <dial_prefix> </dial_prefix> <status> </status> <host> </host> <username> </username> <password> </password> <register> </register>

Advanced <voice_compression> </voice_compression> <dtmfmode> </dtmfmode> <timeout> </timeout> <callerid> </callerid> <clidusage> </clidusage>

Inbound Routing

<id> </id> <priority> </priority> <name> </name> <event> </event> <timezones> </timezones> <action> </action>


© 2006 - 2007 Linugen 28

Outbound Routing

<id> </id> <priority> </priority> <name> </name> <prefix> </prefix> <destinations> </destinations> <timezones> </timezones> <trunk_sequence> </trunk_sequence>

Call Groups

<id> </id> <name> </name> <extension> </extension> <extensions> </extensions> <group> </group> <clidprefix> </clidprefix> <ringtime> </ringtime> <rec_in> </rec_in> <status> </status>


Call Queues

<id> </id> <name> </name> <extension> </extension> <extensions> </extensions> <group> </group> <trunks> </trunks> <clidprefix> </clidprefix> <pin> </pin> <status> </status>

Recordings <greeting_user> </greeting_user> <greeting_member> </greeting_member> <musiconhold> </musiconhold> <announce> </announce> <queue_youarenext> </queue_youarenext> <queue_thereare> </queue_thereare> <queue_callswaiting> </queue_callswaiting> <queue_holdtime> </queue_holdtime> <queue_minutes> </queue_minutes> <queue_seconds> </queue_seconds> <queue_thankyou> </queue_thankyou>


© 2006 - 2007 Linugen 29

<queue_lessthan> </queue_lessthan> <queue_reporthold> </queue_reporthold> <periodic_announce> </periodic_announce>

Advanced <strategy> </strategy> <timeout> </timeout> <retry> </retry> <weight> </weight> <wrapuptime> </wrapuptime> <maxlen> </maxlen> <announce_frequency> </announce_frequency> <periodic_announce_frequency> </periodic_announce_frequency> <announce_holdtime> </announce_holdtime> <monitor> </monitor> <joinempty> </joinempty> <reportholdtime> </reportholdtime>


Conferences

<id> </id> <name> </name> <extension> </extension> <pin> </pin> <admin_pin> </admin_pin> <status> </status>

Advanced <options> </options>

Interactive Voice Response

<id> </id> <name> </name> <extension> </extension> <allow_local> </allow_local> <status> </status> <digit_0> </digit_0> <digit_1> </digit_1> <digit_2> </digit_2> <digit_3> </digit_3> <digit_4> </digit_4> <digit_5> </digit_5> <digit_6> </digit_6> <digit_7> </digit_7> <digit_8> </digit_8> <digit_9> </digit_9>


© 2006 - 2007 Linugen 30

<digit_10> </digit_10> <digit_11> </digit_11>


Advanced <greeting> </greeting> <timeout> </timeout>

Address Book

<id> </id> <extension> </extension> <destination> </destination> <name> </name> <comment> </comment>

Prompts

<id> </id> <name> </name> <filename> </filename> <comment> </comment>

Music On Hold

<id> </id> <name> </name> <filename> </filename> <folder> </folder> <comment> </comment>

Folders <id> </id> <name> </name> <comment> </comment>

General

<default_language> </default_language> <emailvmbody> </emailvmbody> <emailfaxbody> </emailfaxbody> <emailrecbody> </emailrecbody> <fromaddr> </fromaddr>


© 2006 - 2007 Linugen 31

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> </id> <name> </name> <prefix> </prefix> <destination> </destination>

Date and Time

<use_server> </use_server> <server> </server> <year> </year> <month> </month> <day> </day> <hour> </hour> <minute> </minute> <dst> </dst> <location> </location>

Network

<hostname> </hostname> <use_server> </use_server> <ip> </ip> <nat_ip> </nat_ip> <netmask> </netmask> <network> </network> <broadcast> </broadcast>


© 2006 - 2007 Linugen 32

<gateway> </gateway> <dns_1> </dns_1> <dns_2> </dns_2> <smtp> </smtp>

Telephony

<location> </location> <switchtype> </switchtype> <nationalprefix> </nationalprefix> <internationalprefix> </internationalprefix> <echocancel> </echocancel> <echotraining> </echotraining> <card1> </card1> <card2> </card2> <card3> </card3>


© 2006 - 2007 Linugen 33

XML Payload Types

Management > Users > All Users 1 Management > Users > All Groups 2 Management > Extensions > All Extensions 1 Management > Extensions > Suggest Extension 2 Management > Trunks > All Trunks 1 Management > Routing > All Inbound Routes 1 Management > Routing > All Outbound Routes 2 Management > Call Groups > All Call Groups 1 Management > Call Groups > Suggest Call Group 2 Management > Call Queues > All Call Queues 1 Management > Call Queues > Suggest Call Queue 2 Management > Conferences > All Conferences 1 Management > Conferences > Suggest Conference 2 Management > IVRs > All IVRs 1 Management > IVRs > Suggest IVR 2 Management > Address Book > All Address Book Records 1 Management > Address Book > Suggest Address Book Record 2 Management > Recordings > All Prompts 1 Management > Recordings > All Music On Hold 2 Management > Recordings > All Recordings 3 Management > Fax > All Faxes 1 Management > General > All General 1 Management > General > All Phone Types 2 Management > General > All Services 3 Management > General > All Destinations 4 Management > General > All Time Zones 5 Configuration > Date / Time > All Date / Time 1 Configuration > All Network > All Network 1 Configuration > Telephony > All Cards 1 Configuration > Telephony > All Telephony 2 Configuration > Updates > All Updates 1 Configuration > License > All License 1

APPENDIX

III


© 2006 - 2007 Linugen 34

XML Action Types

Build Configuration a0CA Build Dialplan a0ca Build Dialplan Services a0cb Build Dialplan Extensions a0cc Build Dialplan Call Groups a0cd Build Dialplan Call Queues a0ce Build Dialplan Conferences a0cf Build Dialplan IVRs a0cg Build Dialplan Inbound Routes a0ch Build Dialplan Outbound Routes a0ci Reload Asterisk a0d Restart Asterisk a0e Restart HTTPD a0eb Start Asterisk a0f Stop Asterisk a0g Shutdown Server a0h Reboot Server a0i Optimize Database a0j Reload Network a0k Restart Network a0l Start Network a0m Reset CDR a0n Reset Logs a0nb Apply Network a0o Apply Telephony a0ob Apply Date/Time a0p Build TFTP Configuration a0q Build SSL Certificate a0r Factory Reset a0s

APPENDIX

IV


© 2006 - 2007 Linugen 35

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

APPENDIX

V


© 2006 - 2007 Linugen 36

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 Extension not found 0 Idle 1 In Use 4 Unavailable 8 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 37

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 38

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 39

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 40

AMI Events

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>

APPENDIX

VI


© 2006 - 2007 Linugen 41

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 42

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 43

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 44

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 45

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 46

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 47

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

Documents

Sipcat-DeveloperGuide-1.0