Perl VoIP developers 101

Part 1: Perl example on sending SMS, making VoIP calls

If you are a Perl developer and you are curious about how to use the Ozeki Phone System, then this guide is made for YOU. After reading this, you will be able to make/receive voice calls and send/receice text messages.

Part 2: Perl example on Recording VoIP calls, call routing

1. What you need

2. Get started

Overview

HTTP API enables to get information from the PBX in real time and to control calls with HTTP requests. Take a look at how does it work through the example of Call command. Call command can be used to initiate a voice call. It makes an API extension call a number and do tasks with the call. The tasks are declared in an OzML response document as seen in Figure 1.

how does call command work
Figure 1 - How does the Call command work

Step 1: Create a call using a HTTP request, for example: 

http://ozekixepbx.ip:7780/?command=Call&Dialed=100&ApiExtension=9997&Url=<? echo urlencode('http://yoursite.com/callconnected.php'); ?>

Step 2: Accept the CallConnected request from the Ozeki Phone System on your webserver and return an XML to handle the call. Example request sent by Ozeki Phone System PBX to your webserver: http://yoursite.com/callconnected.php Please change the ozekixepbx.ip text to the IP address where the Ozeki Phone System is installed. On the yoursite.com the address should be that where the sample applications are running.

OzML example response returned by callconnected.php: 

<Response>
<Delay>1</Delay>
<Speak>Congratulations, this is your first OzML Response command.</Speak>
<Delay>2</Delay>
<Speak>Have a nice day!</Speak>
</Response>

Code example 1 - OzML Response

To send a test response to a call connected request in a simple manner using the tester, fill out the Response OzML field. You can choose from Example OzMLs or write your own one.

User guide

The Ozeki Phone System provides an opportunity to access certain functions through HTTP API. For example, Making and Receiving calls, Sending and Receiving SMS messages and so on. You can reach these functions by adding and configuring API Extensions through the Ozeki Phone System. There is useful information on how to set up HTTP API on the website.

Continue and install the latest version of Perl.
So you can compile and test codes. After installing Perl, it may happen, that you need to reset your PC.

If you want to use HTTP API, you need to have a webserver, where your written codes can be executed. For simplification, choose Apache by Wampserver. (Of course, you can choose whatever you want!) After you install Wampserver, change the sets of Apache and the value of Listen 80 to Listen 8080 (or something what is not used anywhere else, so you can avoid port conflict) in httpd.conf file.
Besides, you need to make further changes to the settings, so Perl can work properly. If you used the default directories supplied by the Apache installer, it would be: 

C:\Program Files\Apache Group\Apache\conf\httpd.conf

Search the rows below, and change them! 

Before:  AddHandler cgi-script .cgi
After: AddHandler cgi-script .cgi .pl

Before: Options Indexes FollowSymLinks
After: Options Indexes FollowSymLinks ExecCGI

Search the line below (the path can be different) and if you find # at the beginning of the line, please delete it. 

ScriptAlias /cgi-bin/
"C:/Program Files/Apache Group/Apache/cgi-bin/"

After you change the settings, the service has to be reset. Then open the folder, where you installed Wamp and choose the www folder. Here, you can create the required Perl files so you can reach PBX functions. It is important that all created files need to start with the lines below: 

#!c:/Perl64/bin/perl.exe
print "Content-Type: text/plain\n";

Code example 2 - Perl code for required begining lines

Naturally, the path in the first row, change to your own perl.exe path.

Now you need to install an API extension in the Ozeki Phone System in order to receive calls and SMS messages. Find out how to install a new API extension.

3. Receive incoming voice calls

First, create a ReceiveCall folder at www folder, then make a ReceiveCall.pl file at this folder. Add the essential two rows, which was mentioned above.

The process itself:

When a device calls the created HTTP API, it sends a notification to a URL where the API waits for an XML file, which has OzML bases. That will be read to the caller. In Perl method, you only need to print the XML, using Print method. So the program always gives back the text which was entered previously, as a Response to the Request. You can use the XML code what is mentioned in the Code Example 1.

When you are ready, create a subscription to an PBX related event.
Read the following page about the steps of the subscription. Please copy that notifier path (which is available at ReceiveSMS.pl server) into Incoming calls URL field.

When you start a call from an extension to an API, and PBX and webserver are running, you will hear the text which was given in the XML file.
You can find more information at debug level logs about API, the caller, and the system.

4. Make outgoing voice calls

In this section, you will create and send a request to HTTP API, at PBX. Then, PBX will create a call with the information you had given.

Create a Create Call folder in www folder (mentioned above). Add the essential two rows at the beginning of the file, which was mentioned above.
In the file, create a UserAgent which will send the processed request to the PBX, furthermore insert the essential namespace:

use LWP::UserAgent;

$ua = LWP::UserAgent->new;
$req = HTTP::Request->new(GET => "http://yoursite.com:7780/?Command=Call&Dialed=1001&ApiExtension=9000&CallerId=1200&CallerDisplayName=JohnSmith&Url=$url&ErrorUrl=$errorUrl");

Code example 3 - Perl code to create UserAgent and call request

Now, you can see the content of Request with the regurally uploaded name and values of arguments.

After http:// next IP address is IP address of the Ozeki Phone System, and the port is a predefined port of HTTP API (7780 by default). It will call the Dialed number, the device will show the callerID and the Displayname. Make ApiExtension the ID of API Extension!

You can also see the URL and errorURL parameters. URL shows a path which refers to an XML file. This XML has to be created by the syntax rules of OzML language. If you need any help about OzML language find more informations HERE.

The errorURL can be a link to a Perl application, which controls the mistakes (like log files, so you can read them later).
Please do not forget encode the request, before you send it. You can do it with Perl uri_escape() method.
You can send the request with just one row: 

$res = $ua->request($req);

Code example 4 - Perl code to send call request

After testing you can find more help in debug level logs about API, caller and system.

5. Receive SMS message

Create a CreateSMS folder in www folder (which was mentioned above), and then create a CreateSMS.pl file in it. Then write the essential two rows at the beginning of the file.

Process itself:

A device sends an SMS message to the previously created HTTP API. HTTP API send a notification (Request) to your application URL. This request consist of the essential information concering your SMS message. Learn more about it: HERE.

In Perl files, you only need to handle that information. SMS messages will be saved into a file. First, you need to enter POST Request into a variable ($request). 

read(STDIN, $request,$ENV{'CONTENT_LENGTH'}) || die "Could not get queryn";

Code example 5 - Perl code to read POST request into a variable

Then, create a new file, open it and split $request by '&' characters. After, write them every line and close the file. 

open(my $fh, '>>', 'report.txt');
@parameter_list = split(/&/,$request);  
foreach $var(@parameter_list) {
print $fh uri_unescape("$varn");
}
close $fh;

Code example 6 - Perl code to processes the POST request and write into file

When you are ready creating Perl, create a subscription of a new event at PBX. Read the following page about the steps of the subscription. Please copy that notifier path (which is available at ReceiveSMS.pl server) into Incoming messages URL field.

Then, if webserver and PBX are running, send an SMS message to extension 9000 (which was previously installed). You can do this by adding a new extension (e.g. 9100). After click 'HTTP API' menu item in 'Productivity' menu. Now, you click 'Test' submenu and choose SendSms at the right side of 'Select Command'.

sending sms messages
Figure 2 - Sending SMS messages

Set API Extensions to the latest added extension (9100). Filling in the Sender field is optional. In Recipient you should put the oldest added extension (9000). It is not necessery to make a Delivery Report, but you can make one and test your Perl application. If you do everything right, by clicking the Send Request button information about the SMS messages will be showed at your file. If there are any mistakes, you had better check debug logs of the two API and the System. It can happen that messages will not be delivered. Maybe a previously choosed DialPlan rule sent it to an SMPP Outside Line, not to a Recipient. To avoid this, it is useful to turn off all the DialPlan Rules concering Messages.

6. Send SMS message

In this section you will create an HTTP request and send it to the HTTP API at PBX. PBX sends an SMS message with the previously given information through a specified SMPP Outside line. You can find more information, how to set up SMS connection HERE. Create a CreateSMS folder in www folder (which was mentioned above), and then create a CreateSMS.pl file in it. Then write the essential two rows at the beginning of the file. In the file, create a UserAgent which will send the processed request to the PBX, furthermore, insert the essential namespace: 

use LWP::UserAgent;

$ua = LWP::UserAgent->new;
$req = HTTP::Request->new(GET => "http://yoursite:7780/?Command=SendSms&ApiExtension=9000&Sender=1200&Recipient=+361234567&Message=HelloWorld&DeliveryReportURL=$DeliveryReportURL");

Code example 7 - Perl code to create UserAgent and send SMS request

Now, you can see content of Request with the regurally uploaded name and values of arguments. After http:// next IP address is IP address of Ozeki Phone System XE, and the port is a predefined port of HTTP API (7780 by default). Make ApiExtension the ID of API Extension! Sender is sending the SMS, and the Recipient is the device which gets it. This device gets the information of the message as parameters. Delivery Repot can be a link to a Perl application. This will be showed, when the SMS is successfully delivered. You will get a request to this address and with this you can record the previously sent messages. Learn more HERE. Of course, you can write the parameters into just one file, it is simplier. Please do not forget encode the request, before you send it. You can do it with Perl uri_escape() method. You can send the request with just one row: 

$res = $ua->request($req);

Code example 8 - Perl code to send request to PBX

After sending the SMS message, you can check the result at PBX, SMPP Connection or System debug logs. Please check whether it is the right DialPlan Rule is set, because that forwarding the messages to the SMPP.

7. Create a more advanced project

The Ozeki Phone System offers a lot more options for Perl developers. You can interact with existing calls, control and configure the PBX, you can introduce new communication techniques and media formats.
For a complete list of Perl commands, check out: http://www.ozekiphone.com/examples/doc/

Part 2: Perl example on Recording VoIP calls, call routing

If you have any questions or need assistance, please contact us at  info@ozekiphone.com

More information