Creating a New Menu Using the /menus API Service

The Phone.com API includes our /menus service, which you can use to build and manage your Phone.com call menus. Menus present your callers with a list of options for routing their calls; for example, “Press [1] for Sales or press [2] to leave a message.”

Menus rely on you having greetings and routes already set up in your account to support the menu options you want to use. The greeting plays, presenting the caller with the defined menu options. Routes should be in place for each menu option—in the example above, you would set up a route to connect the caller to your Sales queue, and another to connect the caller to voicemail.

This tutorial will show you how to add a new menu with two options, each managed by an existing route. Your menu definition will also specify a menu greeting that plays, as well as an error recording (technically a greeting too) that plays when a caller selects an invalid entry.

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 /menus service. Also, the following topics show you how to structure requests to our API:

Preparing the JSON Object for the New Menu

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


 {
    "name": "<menu name>",
    "allow_extension_dial": "N",
    "outgoing_recording": "<UUID>",
    "invalid_entry_recording": "<UUID>",
    "digits": [
         {
             "digit":"1",
             "route":"<UUID>"
        },
         {
             "digit":"2",
             "route":"<UUID>"
        }
    ]
 }

Parameters:

  • name: The name you want to give your menu. You can use this name later to retrieve the menu using a GET request.
  • allow_extension_dial: If set to Y, this setting allows callers to enter an extension number at any time to bypass the menu and dial that extension.
  • outgoing_recording: The resource ID for the greeting that callers hear when they connect to the phone number. Note that before you create your menu, 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.
  • invalid_entry_recording: The resource ID for the greeting that plays when a caller presses a digit not defined in one of the digits arrays for this menu. Do a GET /media request to find the UUID for this greeting also.
  • digits: An array of digits, defining the digit number and corresponding route for that digit. Note that before you create your menu, you will need to identify the resource IDs for the routes you want to use by doing a GET /routes request.

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

Adding the Menu to Your Account

Now that you’ve prepared the JSON object defining your new menu, 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/menus/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

Then, add the JSON object describing your new menu:


 {
    "name": "<menu name>",
    "allow_extension_dial": "N",
    "outgoing_recording": "<UUID>",
    "invalid_entry_recording": "<UUID>",
    "digits": [
         {
             "digit":"1",
             "route":"<UUID>"
        },
         {
             "digit":"2",
             "route":"<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) {
      $tmp = json_decode($result, true);
      $menu_1 = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your menu is: $menu_1
"; } 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 menu, 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" : "75c98fdd-af89-11e2-b773-8116ab1f72a9"
     }
  }

You now have all the components you need to make a successful POST request to /menus and create your new menu. 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 menu, adding it to your account. Your browser will also display a success message.

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

You can also log into your Phone.com API Developer account and locate the new menu. Simply click Configure > Menus > Manage Menus.


Manage Presets page