Creating a New Route Using the /routes API Service

Note: Our /routes API service allows you to set and manage the feature known as Call Handling Rules in your Phone.com API Developer account settings. Routes are call handling rules by another name, and the Call Handling Rules settings you see when you log into your account will be renamed to Routes in a coming release.

The Phone.com API includes our /routes service, which you can use to build and manage rules for call routing. The service lets you route calls to one or more destinations, either automatically or based on menu options that callers can select.

This tutorial will show you how to add a new route that will first play a greeting and then route the caller to a queue you have already created (see Creating a New Queue Using the /queues API Service).

In This Tutorial:

Prerequisites

To complete this tutorial, you will need:

Before beginning this task, please refer to Systems and Requirements and the reference information for the /routes service. Also, the following topics show you how to structure requests to our API:

Preparing the JSON Object for the New Route

First, we will construct the JSON object that describes attributes for the new route as follows:


 {
    "name": "<route name>",
    "rules": [
      {
         "action": "play",
         "recording": "<UUID>",
         "action": "queue",
         "queue": "<UUID>"
       }
     ]
 }

Parameters:

  • name: The name you want to give the route. You can use this name later to retrieve the route using a GET request.
  • action: The action to be taken once the call is connected; in this case, play to play the greeting, followed by queue to forward the caller to the specified queue.
  • recording: The resource ID for the greeting that callers hear when they connect to the phone number. Note that before you create your route, you will need to find the resource ID for the greeting you want to use by doing a GET /media request. This field is required for play action.
  • queue: The resource ID of the queue to which the caller will be connected.

When you send this JSON object to the Phone.com API using a POST request to the /routes service, our system will generate the new route. When that route is later invoked, our system will play the greeting and then route the caller to the specified queue. For a full list of available parameters that can be defined in the object, see POST /routes.

Adding the Route to Your Account

Now that you’ve prepared the JSON object defining your new route, we can go ahead and build the API request. In this tutorial, we’ll build our request using PHP, but you can use any language that can make HTTPS requests. If you would prefer to make your request using cURL, see Making API Requests Using cURL.

At the beginning of the request, we need to define the URL for the Phone.com API, and provide the API Key and API Password configured for your application.


  <?php

  $url     = 'https://v1.api.phone.com/routes/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

Then, add the JSON object describing your new route:


 {
    "name": "<route name>",
    "rules": [
      {
         "action": "play",
         "recording": "<UUID>",
         "action": "queue",
         "queue": "<UUID>"
       }
     ]
 }

And your cURL code:


  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);

  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "$app_key:$app_pwd");

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

Finally, you will need to write code to parse the response sent back to your application by our API server.


  if($info == 200 || $info == 201) {
      $routes_1 = json_decode($result, true);
      $uuid = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your route is: $routes_1<br>";
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
  }

  ?>

Note that a successful response will return an HTTP 200 OK code and include the resource ID (UUID) for your new route, which allows you to check on its status. An HTTP 4xx code would indicate a problem in your request, and an HTTP 5xx code would indicate a problem with the Phone.com API service.

A sample response would be:


  {
     "response" : {
        "results" : "85c94fdd-ab89-11e2-b773-8206ab1f72e1"
     }
  }

You now have all the components you need to make a successful POST request to /routes and create your new route. Use the code snippets we created above to make your request, or copy and use the full code sample below.

How Do I Know it Worked?

Running the Copy the Code sample below in a web browser will create your route, adding it to your account. Your browser will also display a success message.

Example: Success! The ID for your route is: 85c94fdd-ab89-11e2-b773-8206ab1f72e1

You can also log into your Phone.com API Developer account and locate the route (called a Call Routing Preset in your settings). Simply click Configure > Call Routing Presets > Manage Presets).


Manage Presets page

Copy the Code

The full set of PHP code for this tutorial is shown below.


  <?php

  $url     = 'https://v1.api.phone.com/routes/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

  $payload = <<<JSON
   {
      "name": "<route name>",
      "rules": [
        {
           "action": "play",
           "recording": "<UUID>",
           "action": "queue",
           "queue": "<UUID>"
         }
       ]
   }
  JSON;

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);

  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "$app_key:$app_pwd");

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  if($info == 200 || $info == 201) {
      $routes_1 = json_decode($result, true);
      $uuid = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your route is: $routes_1<br>";
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
  }

  ?>

Learn More: