Clint Berry

Full-stack Web Developer

Wannabe Entrepreneur

Getting Started With Plivo

Posted on 24 Aug 2011 in Plivo, Telephony | 25 comments

The open-source telephony development world has been changing drastically over the last 2 years. Projects like FreeSWITCH allow you to create simple phone applications with XML files, but until recently, advanced applications required a solid knowledge of the Erlang language. Then enters Twilio– which allows any web developer to make advanced telephony apps in the web language of their choice. But with Twilio’s pricing structure, you are looking at anywhere from 2 to 4 cents per minute IN ADDITION to your VOIP service while also being locked-in to their cloud. Must I learn Erlang if I want to make cool telephony apps for free?

Enter Plivo

Then on May 26, 2011, the Plivo project was announced. Plivo is essentially an open source Twilio extension that works with FreeSWITCH. What does it mean? It means you can build advanced telephony apps using whatever web programming language you want via the Plivo Framework… FOR FREE! Yes, that is right, you can build a simple PBX system for your company’s phone system with PHP. You can create a skill-based routing server in python. And my personal favorite, you can create real-time web-phones with NodeJS. It truly is amazing. Read more about Plivo. But enough of my babbling. Let’s get to the good stuff.

Getting Started

I have encountered a few people on the #plivo IRC chat having trouble getting Plivo going. They usually are web developers, new to FreeSWITCH like me. The beautiful part about Plivo is you don’t need to be a FreeSWITCH expert (although it doesn’t hurt).

Step 1 – Prepare your Box

You need a place to install FreeSWITCH and Plivo. If you don’t have an extra box lying around I recommend using a virtual Ubuntu Linux machine for development. I prefer to use the free program Virtual Box to power my virtual machines. I also suggest grabbing the Turnkey linux ISO which is a basic Ubuntu ISO image ready to go. If you need extra help getting your virtual machine setup, follow these instructions: How to Setup Turnkey Linux on Virtual Box.

If you are planning to give public access to your app then I recommend using VPS.net for a cheaper entry into cloud hosting.

Step 2 – Install FreeSWITCH

A big thanks to the guys at Plivo for providing a simple shell script for installing FreeSWITCH. Switch to your home directory and enter these commands into your shell (taken directly from Plivo website):

wget --no-check-certificate https://github.com/plivo/plivoframework/raw/master/freeswitch/install.sh
bash install.sh

Let it run for a few minutes and you will have a working copy of FreeSWITCH ready to go.

[box type="note" style="rounded" border="full"]Keep in mind that this install script will only work for CentOS 5.5+ and Debian-based Distros (Ubuntu)[/box]

Step 3 – Install Plivo

Yet another easy installation thanks to the Plivo guys…

wget --no-check-certificate https://github.com/plivo/plivoframework/raw/master/scripts/plivo_install.sh
bash plivo_install.sh /usr/local/plivo

Again, it should run for a bit and when it is done it should be ready to go.

Step 4 – Configure Your Dialplans

Since most web developers don’t come from a Telephony background, the whole FreeSWITCH thing is new. On the #plivo IRC channel, I see new people, usually web developers like me, getting stuck at this spot all the time.

Dialplan Basics

The dialplan in freeswitch essentially tells freeswitch how to route calls when they come in. An out-of-the box freeswitch setup installs 20 extensions (just like an office phone system) with passwords to login. The extensions are 1000-1020 and all have the same password – 1234. With the Plivo FreeSWITCH installer, the default dialplan is overwritten to intercept all calls and those extensions don’t work very well anymore. If you are just getting started with the whole freeswitch thing, I have provided an alternate version of the dialplan file to allow you to do testing of your freeswitch install as well as develop Plivo apps.

Download Dialplan Here – default.xml

Copy that dialplan into the freeswitch/conf/dialplan directory. This dialplan is the same as the out of the box FreeSWITCH dialplan, except I added the plivo config and restricted it to extension 1005. This means the rest of your extensions will work like normal so you can see how awesome freeswitch is. Restart freeswitch by typing ‘shutdown’ in the freeswitch terminal.

Step 5 – Get a Free SoftPhone For Testing

Now things start to get fun. Get a free soft phone. For osx I got Blink Lite. Once you get a free soft phone you can login to your FreeSWITCH install by extension and IP address. If you installed freeswitch on 192.168.1.5 then for your credentials on your softphone you would use [email protected] as the user, and 1234 as the password. You should get logged right in and now you can call any other extension. Try dialing 1001 and you should get taken to voicemail. Pretty sweet right? Try dialing 1005 and right now you should get nothing but a disconnected call, since 1005 is now connected to plivo.

Step 6 – Configure Plivo

The last step before you take over the world with your new telephony app is configuring plivo. This is extremely easy. Go to your plivo install directory (typically /usr/local/plivo) and go to the etc/plivo directory. Open the default.conf file and look for these directives:

DEFAULT_ANSWER_URL = http://127.0.0.1:3000/answer/
DEFAULT_HANGUP_URL = http://127.0.0.1:3000/hangup/

Typically your web server won’t be tied to port 3000. You need to change these values to point to your web server IP address and port (typically 80). Also, change the URL to point wherever your app will be. I will leave mine pointing to /answer. Then make sure FreeSWITCH is started and go ahead and start plivo:

/usr/local/plivo/bin/plivo start

Step 7 – Hello World

FINALLY, TIME FOR AN AWESOME PHONE APP! Your system is all setup, and plivo will be answering all calls on extension 1005. Let’s write our first app. I will make this first app in PHP, but I won’t be doing anything special, it will work on any web language that can serve an xml file. Since plivo is pointing to answer/ I will create answer/index.php and inside that file I will put plivo response xml code:

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
     <Speak>Hello World</Speak>
</Response>

Now open your soft phone and dial 1005. You should hear a pleasant voice, saying “hello world”. It should be an exciting moment for you.

Now your limits are endless. Write some amazing telephony apps in a web language and let me know some of the cool projects you are building. I’ve got several more posts planned about building plivo apps coming in the next few weeks, so be ready for some exciting developments.

The following two tabs change content below.
I am a full-stack web developer that is passionate about start-ups.

25 comments

  1. whitebook / August 28th, 2011 12:19

    Hey Clint Great Article.

    Thanks.

  2. pulakkil / November 13th, 2011 16:15

    Nice tutorial for beginners

  3. serhat yılmaz / November 18th, 2011 12:18

    hi,

    my plivo default installation path is usr/share/plivo.

    for example i have index.php application.

    where sould i put my application file.

    Any help would be greatly appreciated!

  4. Clint / November 18th, 2011 15:21

    @serhat: The idea is to communicate via your web server. You will need to setup apache/php on that box or another box to communicate with plivo via PHP.

  5. Gregor / December 25th, 2011 22:17

    Hi Clint!

    Great article.

    You have changed default.xml to send only call to 1005. And such scenario is even more powerfull.

    I would like to send calls to plivo according to dialplan. Is there a way to pass some variable from dialplan rule to plivo so that plivo would use this variable as answer url, insted of default one.

    Is there a way or only to hack plvo source code?

  6. Rohit Ayare / December 27th, 2011 9:50

    Hi Clint,

    Any Video Tutorials about plivo

    Want to learn how this thing works

    What should i do

    and i want to do via PHP

  7. Karan Ratanpal / March 8th, 2012 23:14

    Hi Clint,
    This is a great article. By using your default.xml file, I am able to make calls using the regular extensions and the freeswitch functions properly.
    But when I am dialing the 1005 extension. my freeswitch shows a 407 & 480 error on the console. I am able to access the php file through the web browser.
    Kindly please give me some pointers regarding what I can do to fix this issue.

  8. Antonello / May 7th, 2012 17:14

    Hello,
    I have installed FS+PLIVO with your instructions.

    But, when I dialed 1005 … not answer … I have changed the port in “DEFAULT_ANSWER_URL” from 80 … 8084 … 8088 … in some case I hear a free line …

    where I wrong ?

    Antonello

  9. Clint / May 9th, 2012 14:13

    @Antonello – Did you add the dial plan I provided to freeswitch? Otherwise it won’t work. Feel free to come into IRC on the #plivo channel if you have questions, or also the google group

  10. Praveen / August 27th, 2012 7:13

    Hi clint,
    The source files for plivo in the git repo seems to be moved. Can you update the new location ?

    Thanks.

  11. Clint / August 30th, 2012 18:05

    Thanks Praveen, just updated.

  12. BigA / September 4th, 2012 21:38

    Thanks for sharing your experience with Plivo!

    Do you know how I can change the default Plivo/FreeSWITCH voice? Also, can I download other voices from somewhere?

    BTW, your custom dialplan — default.xml — link is broken.

  13. Sri / September 23rd, 2012 3:58

    Thanks a lot for the tutorial. However, I’m stuck because the link to the default.xml dialplan is broken. Is there any way you could provide another link?

    Kind Regards,
    Sri

  14. Clint / September 24th, 2012 15:25

    @Sri, Sorry about that. I should never have tried to run my own link shortening service :-) I updated the article, and here is the new link: http://clintberry.com/download/default.xml

  15. Sri / September 25th, 2012 4:46

    Hi Clint, thanks a bunch. That worked beautifully. I tested using the X-Lite softphone (by CounterPath) on my Mac and I was able to connect to the FreeSwitch+Plivo setup running on a CentOS 6.3 box. Here’s another question I’d really appreciate if you could help with. What do I need for Plivo or the softphone to call local/long-distance numbers? Do I need to establish a SIP trunk between FreeSwitch and a SIP provider like Vonage?

    Kind Regards,
    Sri

  16. Clint / September 25th, 2012 16:26

    @Sri – Yes, that is exactly what you need to do. I don’t have a tutorial out there for setting up trunks with FreeSWITCH, but you can find most the info you need on the wiki, or work with a trunking provider that is familiar with FreeSWITCH. Good luck! Also note, that default.xml file is not secure in any way. You need to go customize it according to your needs.

  17. stewart / January 9th, 2013 22:44

    Nice tutorial. I’m having trouble when dailing 1005 after creating the index.php file in the answer directory under my webroot. When I dail I get “failed with reason NORMAL_CLEARING”

    I am using your dailplan.xml and made all the configuration changes you mentioned. I am using FSComm as the softphone from a windows vista machine. I am running freeswitch and plivo in unbuntu 12.10 on a separate physical machine than the on the softphone is installed on.

    Help please!

  18. Clint / January 28th, 2013 4:28

    @stewart – Sadly I haven’t kept this code up to date. I will have to revisit it when I can and go through all the steps again to make sure it is working.

  19. Maqbool / January 29th, 2013 13:14

    I was wondering, if it is possible to accept touch prompt from users and then build workflows using plivo? For example asking for users to enter 1 if the accept 2 if not and then feed that response back to server? Thanks.

  20. Panda / January 30th, 2013 16:32

    You tutorial really helped me. Thank you.

    (Please remove the semi-colons from the ‘answer/index.php’ code block – some people may be confused by this)

  21. Clint / January 30th, 2013 17:09

    @Maqbool – It absolutely is. You’ll have to check with the docs. I am on my phone right now.

  22. Clint / January 30th, 2013 17:11

    @Panda – Thanks! and thanks for the catch… weird semi-colons removed.

  23. myphonerobot / June 9th, 2013 16:13

    Hello client,

    I tried to install freeswitch both on ubuntu and cent os 6.2 but in both cases, the installation did not even created a freeswitch directory in usr/local…any idea what might be wrong?

    regards.

  24. Clint Berry / June 19th, 2013 5:01

    @myphonerobot – Do you get any errors when you run the shell scripts at http://docs.plivo.org/get-started/ ?

  25. myphonerobot / June 25th, 2013 11:03

    Clint, it’s all fixed now and it works as a charm! the problem was that I was trying to test Freeswitch from local VM image. when I run all the steps on actual hosting , it went all fine. Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>