Server Infrastructure Required

This lab can be completed if you have access to the server infrastructure in a private lab or if you are at an event such as Cisco Live!

Managing Phone Numbers

Level: Beginner

In this lab, you'll learn how to write a script that will provision new phone numbers for an app using the Tropo REST API.

Objective

Completion Time: 20 minutes

  • Provision a number using a web page you create

Prerequisites

  • You should have some basic knowledge of Javascript before you start this lab.
  • Basic knowledge of HTML is helpful, but not required.

Getting Started

  1. From the Tropo dashboard, log into your account and click Create New App.
  2. Name your app 'Phone Number Provisioning'.

The script we will create will only be used for testing the addition of a new phone number. For this reason, we'll create a very basic application.

  1. Select Scripting API under the Type of Application.
  2. Open the script editor by clicking the pencil icon titled New script.
  3. Use the say method to create a message that should play when someone calls the newly provisioned phone number.

    say("Success! The number you dialed is associated with this App!");
    
  4. Name your file 'provisioning.js' and click Save and close.

  5. Click CREATE APP.

    The next page will show your App Details. You'll notice that your URL now has a 7-digit number shown after /applications/. This is your application's ID.

  6. Copy the 7-digit application ID number at the end of the resulting page's URL.

Creating your HTML application

  1. Create a new HTML file in any text editor, and use a <script> element to include JQuery into the file, like this:

    <!DOCTYPE html>
    <html>
    <head>
       <meta name="description" content="Tropo provision new number">
       <script src="https://code.jquery.com/jquery-2.2.4.js"></script>
       <title>Provisioning</title>
    </head>
    <body>
    </body>
    </html>
    
  2. Inside the <body> element, create a button and a <div> where the result of the provisioning will be displayed.

    <!DOCTYPE html>
    <html>
    <head>
       <meta name="description" content="Tropo provision new number">
       <script src="https://code.jquery.com/jquery-2.2.4.js"></script>
       <title>Provisioning</title>
    </head>
    <body>
    
    <input type="button" value="add a number" id="activate" />
    <div id="result"></div>
    
    </body>
    </html>
    
  3. Create a <script> element inside the <body> and declare the following three variables (replacing the values of username and password with the username and password you use to log into the Tropo dashboard).

    <script>
    var USERNAME = "Your Tropo username";
    var PASSWORD = "Your Tropo password";
    var newNumber;
    </script>
    
  4. Write a JQuery event handler to make an AJAX call when the button is clicked.

    <script>
    var USERNAME = "Your Tropo username";
    var PASSWORD = "Your Tropo password";
    var newNumber;
    $(function() {
       $("#activate").on("click",function(){
           $.ajax({
               url: "https://api.tropo.com/v1/applications/(id)/addresses",
               method: "POST",
               headers: {
                   "Authorization": "Basic " + btoa(USERNAME + ":" + PASSWORD)
               },
               data: {
                   "type":"number"
               }
           })
       });
    });
    </script>
    
  5. In the value of the url property, replace (id) with your application ID, which you copied in Step 8.

    Security Note: The username and password are viewable in the HTML source. Additionally, the AJAX method is passing your username and password to the API after encoding them as a Base 64 string. In a production application, you'll want to take steps to protect your login information.

  6. Write a method that will run in the case of an error and that will return the error. This should be chained to the end of the ajax method. For example:

    $(function() {
    
       $("#activate").on("click",function(){
           $.ajax({
               url: "https://api.tropo.com/v1/applications/(id)/addresses",
               method: "POST",
               headers: {
                   "Authorization": "Basic " + btoa(USERNAME + ":" + PASSWORD)
               },
               data: {
                   "type":"number"
               }
    
           }).fail(function (jqXHR, exception) {
                       var msg = '';
                       if (jqXHR.status === 0) {
                           msg = 'Didn\'t connect.\n Verify Network.';
                       } else if (jqXHR.status == 404) {
                           msg = 'Requested page not found. [404]';
                       } else if (jqXHR.status == 500) {
                           msg = 'Internal Server Error [500].';
                       } else if (exception === 'parsererror') {
                           msg = 'Requested JSON parse failed.';
                       } else if (exception === 'timeout') {
                           msg = 'Time out error.';
                       } else if (exception === 'abort') {
                           msg = 'Ajax request aborted.';
                       } else {
                           msg = 'Uncaught Error.\n' + jqXHR.responseText;
                       }
                       $('#result').html(msg);
           })
    
      });
    });
    
  7. Write a method to run if the AJAX request succeeds.

    $(function() {
    
       $("#activate").on("click",function(){
           $.ajax({
               url: "https://api.tropo.com/v1/applications/5064888/addresses",
               method: "POST",
               headers: {
                   "Authorization": "Basic " + btoa(USERNAME + ":" + PASSWORD)
               },
               data: {
                   "type":"number"
               }
    
           }).fail(function (jqXHR, exception) {
               var msg = '';
               if (jqXHR.status === 0) {
                   msg = 'Didn\'t connect.\n Verify Network.';
               } else if (jqXHR.status == 404) {
                   msg = 'Requested page not found. [404]';
               } else if (jqXHR.status == 500) {
                   msg = 'Internal Server Error [500].';
               } else if (exception === 'parsererror') {
                   msg = 'Requested JSON parse failed.';
               } else if (exception === 'timeout') {
                   msg = 'Time out error.';
               } else if (exception === 'abort') {
                   msg = 'Ajax request aborted.';
               } else {
                   msg = 'Uncaught Error.\n' + jqXHR.responseText;
               }
               $('#result').html(msg);
           }).done(function(msg) {
               newNumber = msg.href.substr(msg.href.length - 11);
               $('#result').html("Here's your new number: " + newNumber);
           });
       });
    });