Telestax Blog

RestCommONE Sip Tutorial – Basic Usage and Voice DTMF

What is RestCommONE?

RestCommONE is a carrier-grade open source platform that provides developers the tools to integrate fax, voice, and SMS functionality into their own applications with ease. In order to highlight the ease of use and help voice application developers quickly get started with RestCommONE, this tutorial will help you along the way.

Requirements:

You will need to have a sip phone installed on your computer. In this tutorial, we shall be using Linphone. It can be downloaded HERE. If you are running on a Linux operating system, you can try (sudo yum install linphone). On a windows system, just follow the Windows installation process.

You will also need to download Mobicents Sip Servlet Container and Mobicents Media Server. For testing purposes, please download the binary HERE.

This should download a zip file similar to this (restcomm-saas-jboss-1.0.0.BETA2-SNAPSHOT.zip). Unzip the file to any convenient directory on your computer.  You may use WinZip or the free 7-zip to get the content of the zip file. For Linux users, run (unzip restcomm-saas-jboss-1.0.0.BETA2-SNAPSHOT.zip).

You will also need to make sure you have cURL installed on your computer. You can get it HERE.

Starting RestCommONE

Once you have unzipped the file, you should have a directory called restcomm-saas-jboss-1.0.0.BETA2-SNAPSHOT. This directory will be referred to as $RESTCOMM_HOME.

go to the directory $RESTCOMM_HOME/mobicents-media-server/bin

(on Linux )

change the permission of the (run.sh) file to make it executable. You can do that as follows (sudo chmod +x run.sh) then, run the file as follows:

./run.sh

(on Windows)

You have to execute the (run.bat) file.

It is best to do this from the cmd command line instead of double clicking on the .bat file

The above command will start the Mobicents Media Server.

(Open another command line windows)

go to the directory $RESTCOMM_HOME/bin

(on Linux)

execute the command (./run.sh)

(on Windows)

execute the command (run.bat)

The above command will start the Mobicents Sip Servlets JBoss container.

You will now need to copy and paste this curl command onto your CMD or Linux  command line terminal.

NOTE: The curl command below should be copied and pasted as a single line.

curl –data “PhoneNumber=1234&VoiceUrl=http://127.0.0.1:8080/restcomm/demo/hello-world.xml&VoiceMethod=POST” http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers.json

 

Once the curl command completes successfully, you should see an output similar to the one below

———————————————————————————————————-

 “sid”: “PNe18d9c8599414a868ea35d9203bec5df”,
“account_sid”: “ACae6e420f425248d6a26948c17a9e2acf”,
“friendly_name”: “234”,
“phone_number”: “+1234”,
“voice_url”: “http://127.0.0.1:8080/restcomm/demo/hello-world.xml”,
“voice_method”: “POST”,
“voice_fallback_method”: “POST”,
“status_callback_method”: “POST”,
“voice_caller_id_lookup”: false,
“date_created”: “2013-01-29T14:35:49.381-06:00”,
“date_updated”: “2013-01-29T14:35:49.381-06:00”,
“sms_method”: “POST”,
“sms_fallback_method”: “POST”,
“api_version”: “2012-04-24”,
“uri”: “/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers/PNe18d9c8599414a868ea35d9203bec5df.json”

———————————————————————————————————-

Testing RestCommONE with a Sip Phone

Start Linphone and  make a call to this sip address (sip:1234@127.0.0.1:5080) as shown in the screenshot below.

linphone_restcomm_test

You will hear a welcome message that is pre-configured with RestComm.

Changing the welcome message.

Go to the $RESTCOMM_HOME./server/default/deploy/restcomm.war/demo directory and use any text editor to open the (hello-world.xml) file. The content should look

like  the screenshot below.

Restcomm_hello-world_xml

 

Change the content of the first line from  <Say>Welcome to RestComm, a TeleStax sponsored project.</Say> to <Say>Welcome to My First Test of RestComm Voice Server.</Say>

Save the changes and make another call from your sip phone to this sip address (sip:1234@127.0.0.1:5080)

You should hear the new message,  “Welcome to My First Test of RestComm Voice Server”.

You can see how easy it is to get RestComm to interact with the simple hello-world.xml welcome message. Now, let us move on to something more advanced.

RestCommONE and DTMF DEMO

 

Getting RestCommONE to work with DTMF requires that you have a script attached to your  xml file. In the section, you will see how you can get user input from a sip phone and process the result. For your convenience, this guide has been simplified so that you can concentrate on the application logic.

Requirements

There are two important files that are required to work with this tutorial.. The first is the restcomm-dtmf-demo.xml. You can download it HERE and move it into your  $RESTCOMM_HOME /server/default/deploy/restcomm.war/demo directory.

The content of the restcomm-dtmf-demo.xml file looks like the screenshot below

restcomm_dtmf_demo_tutorial

Notice that the restcomm_dtmf_demo.xml contains the tag:

<Gather action=”http://telestax-tester.appspot.com/handle-user-input.php” numDigits=”1″>

The <Gather>tag points to a second file that is needed to process user input. In order to facilitate the use of this demo, the php file has been uploaded to an online web server. Your local application can point to the web link and use the dtmf demo application. Below is a screenshot of the content of the handle-user-input.php

Restcomm_dtmf_handle_userinput

In order to bind the restcomm_dtmf_demo.xml to RestComm, you will need to run  cURL command as follows (you can copy and paste to your command line terminal)

curl –data “PhoneNumber=3333&VoiceUrl=http://127.0.0.1:8080/restcomm/demo/restcomm_dtmf_demo.xml&VoiceMethod=POST” http://ACae6e420f425248d6a26948c17a9e2acf:77f8c12cc7b8f8423e5c38b035249166@127.0.0.1:8080/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers.json

 

If successful, you will see the output below

——————————————————————————–

{
“sid”: “PN9c20559c1bce40f7982fa5ee80ff5c1a”,
“account_sid”: “ACae6e420f425248d6a26948c17a9e2acf”,
“friendly_name”: “3333”,
“phone_number”: “+13333”,
“voice_url”: “http://127.0.0.1:8080/restcomm/demo/restcomm_dtmf_demo.xml”,
“voice_method”: “POST”,
“voice_fallback_method”: “POST”,
“status_callback_method”: “POST”,
“voice_caller_id_lookup”: false,
“date_created”: “2013-02-01T09:38:19.450-06:00”,
“date_updated”: “2013-02-01T09:38:19.450-06:00”,
“sms_method”: “POST”,
“sms_fallback_method”: “POST”,
“api_version”: “2012-04-24”,
“uri”: “/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/IncomingPhoneNumbers/PN9c20559c1bce40f7982fa5ee80ff5c1a.json”

——————————————————————————–

Start up linphone with following SIP address <sip:3333@127.0.0.1:5080>

Restcomm_dtmf_dialing3333

 

Listen to the menu options played by the restcomm_dtmf_demo app. Click on the Keypad tab and press 1. You should hear a message telling you that “you are entering the conference room”.

Restcomm_keypad_userinput

 

Changing the handle-user-input.php file

Effort has been made to simplify this tutorial as much as possible. If you want to make changes to the handle-user-input.php file, you will need to host the file yourself on a web server capable of running PHP. Here is a quick overview of what you need to do.

On Windows

  • Install PHP
  • Install Apache Http web server
  • copy the handle-user-input.php into the root of your web server
  • access the file as follows : http://127.0.0.1/handle-user-input.php
  • go to $RESTCOMM_HOME /server/default/deploy/restcomm.war/demo/restcomm_dtmf_demo.xml file and edit the tag <Gather action=”http://telestax-tester.appspot.com/handle-user-input.php” numDigits=”1″> to point to your local server as follows  <Gather action=”http://172.0.0.1/handle-user-input.php” numDigits=”1″>
  • Save the changes and test your application by making a call using linphone or any other sip phone.

On Linux

  • Install PHP (on a Fedora system, sudo yum install php)
  • start the httpd server as follows – sudo service httpd start
  • copy the handle-user-input.php to /var/www/html directory. You may download the handle-user-input.php file HERE
  • access the above user input php file from the local web server as follows : http://127.0.0.1/handle-user-input.php
  • If the installation is successful, you should see an output similar to the one below

<Response>

<Say>You pressed ‘.0.’.</Say>

<Say>But i don’t know what to do with that.</Say>

</Response>

  • go to $RESTCOMM_HOME /server/default/deploy/restcomm.war/demo/restcomm_dtmf_demo.xml file and edit the tag <Gather action=”http://telestax-tester.appspot.com/handle-user-input.php” numDigits=”1″> to point to your local server as follows  <Gather action=”http://172.0.0.1/handle-user-input.php” numDigits=”1″>
  • Save the changes and test your application by making a call using linphone or any other sip phone.

.

Known Issues

When working with this demo, you might encounter exceptions with linphone showing “Server Internal Error” and the output from the Jboss terminal  showing the exception below;

org.apache.ibatis.exceptions.TooManyResultsException: Expected one result (or null) to be returned by selectOne(), but found: 2
    at org.apache.ibatis.session.defaults.DefaultSqlSession.selectOne(DefaultSqlSession.java:63)”

This is often encountered if you run the cURL command with the same phone number twice. The database will have double entry pointing to the same phone number.

To resolve this problem, go to the $RESTCOMM_HOME /server/default/deploy/restcomm.war/WEB-INF/data/hsql/ directory  and delete the content of the restcomm.log file.

The stop and restart the Mobicents Media Server and the JBoss container from the CMD or Bash terminal.

Note

You need to always start the Mobicents Media Server first.

 

 

 

No Comments

Post A Comment

Get awesome content in your inbox every week.

Give it a try. It only takes a click to unsubscribe.