Build a Sales Line Bot using Hipchat and Plivo API

    Everyone has experienced IVRs (interactive voice response). It sounds something like this: “press 1 if you’re a developer, press 2 if you’re an awesome developer”. Here, we will show you how to build an IVR system that use’s HipChat APIs and post details of incoming calls, recordings and voicemails on your Plivo number to HipChat. After each call is complete, our bot also sends the URL of the call recording to the Chat room so that our sales team can have access anywhere anytime.

    Understanding IVR

    Features you will get with the bot:

    • Get details (name, location) of the caller using a service called OpenCNAM
    • Posts to HipChat the details of every call using HipChat API
    • Call Forwarding - Forward the incoming call to the first point of contact (Mobile, PSTN, Browser phone, or any SIP Phone).
    • Call Broadcast - Broadcast the call to multiple numbers incase the first point of contact is not able to answer
    • Voicemail - If no one is able to answer the call, the caller can leave a voicemail
    • Email and SMS Notification - Sends out an email and SMS with the recording of the call
    • Voicemail Transcription- Posts to HipChat room the transcript if call goes to voicemail

    This app is essentially simliar to Google Voice. Think about Google Voice as an app that uses a single phone number that does routing/fowarding, transcription, email, SMS, IVR, and voicemail, which is exactly what we’re building here. This means that with a few changes to this HipChat API integration, you can build your own app that essentially emulates Google Voice. Be sure to look out for our follow up post that will feature this hack and include a GUI as well.

    HipChat API mobile screencap HipChat API mobile screencap2

    Here’s a demo:

    Get Started

    We are going to build our app using Flask, Heroku and Plivo. The goal of this tutorial is to get you started with Plivo APIs and XML and quickly prototype and deploy apps on heroku. We will be leveraging three Plivo XML elements, GetDigits, Dial and Speak to create this application.


    1. Get a Free Plivo Trial Account: upon signup and verification, you will receive a SMS enabled Plivo Number, your Plivo Auth ID, and your Plivo Auth Token.
    2. Get a HipChat account: head over to the Heroku documentation to get accquianted on how to setup an account and install the Heroku toolbelt.
    3. Install Python and Virtualenv: see this guide for guidance.

    Start Building

    1. Get the latest source code by typing the following in the terminal and hit Enter.

      $ git clone $ cd wrench

    2. Open the file in this folder in your favorite text editor and add the Plivo and HipChat credentials.


    Get the Plivo Auth ID and Auth Token from the dashboard.

    HipChat API Bot - Auth ID Token

    Enable HipChat API Access by creating a token here

    HipChat API Bot - Auth Token

    1. Open the file in this folder in your favorite text editor. Create a HipChat roomand add it to the VOICEMAIL_HIPCHAT_ROOMS list.

      # The first phone number the call needs to be forwarded to FIRST_CONTACT = ‘’ # Eg. 15555555555. Make sure you add the country code. # Needs to be a list of numbers the call will be broadcasted # if it does not get answered by the FIRST_CONTACT BROADCAST_CONTACTS = [’’] # Eg. 15555555555. Make sure you add the country code. # Add the Plivo Number you purchased in step 1. SMS_SOURCE_NUMBER = ‘’ # Needs to be a list of numbers. The SMS with the voicemail recording # will be sent to these numbers. VOICEMAIL_SMS_RECEIVERS = [’’] # Eg. 15555555555. Make sure you add the country code. # All notifications will be sent the HipChat Rooms. VOICEMAIL_HIPCHAT_ROOMS = [’’] #Add HipChat Room Names

    2. Commit your changes.

      $ git add $ git commit -m ‘Adding credentials and config’

    3. Create a heroku app by typing the following command in your terminal. Take a note of your app url, in this case it’s

      $ heroku create Creating pacific-chamber-7397… done, stack is cedar Git remote heroku added
    4. Deploy your code to heroku and add the redistogo add on.

      $ git push heroku master $ heroku scale web=1 $ heroku scale worker=1 $ heroku addons:add redistogo

    Note: For each application, Heroku provides 750 free dyno-hours. To run more than 1 dyno, you may have to verify your heroku account. Make sure you scale down the dynos when you are done testing.

    1. We’ll create a Plivo application and point it to the number you purchased in step 1. Open in your browser.

    HipChat API Bot - Plivo App

    Click on the New Application button to create an application. Give a name to your application, let’s call it ‘Sales Line IVR’. Click on ‘Create’ upon done. Use the answer URL as http://(heroku app url)/response/forward/. Choose the GET method. Leave the other fields as it is for now. Note: Replace “heroku app url” with the the url returned when creating the heroku app in Step 6.

    1. Assign your Plivo number to your new Sales Line IVR App Choose any of your Plivo phone numbers found on your Numbers tab in the Plivo Dashboard to PLIVO_NUMBER. If you don’t yet have a number, you can claim your free local US phone number in the Numbers tab when you click on the “Claim your free local US number” link.

    HipChat API Bot - Plivo Number Page

    Click on the Plivo phone number you wish to associate with your new app, choose the application ‘Sales Line IVR’ in the dropdown and click ‘Update’

    HipChat API Bot - Plivo Number Page

    You are all set! Make a call to your Plivo Number and test it out.

    Is anything on this page unclear? Suggest edits and help us improve our documentation!