Creating a New Queue Using the /queues API Service

The Phone.com API includes a /queues service that you can use to build and manage call queues. Queues feature lets you route incoming calls to a select group of phone numbers or extensions within your phone system. Queues are often used in Sales, Support and Service departments where there is more than one person answering calls. The call is placed in the queue, to be answered by the next available operator.

In this tutorial, we will create a new queue, add it to your account, and retrieve the resource ID of the queue. Once you’ve created a queue, you can use it to build call menus and routes.

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

Preparing the JSON Object for the New Queue

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


 {
    "name": "<queue_name>",
    "caller_id": "<caller ID>",
    "announcement": "<greeting UUID>",
    "hold_music": "<hold music UUID>"
    "max_hold_time": 5,
    "maxhold_forward_selector": "voicemail",
    "extension": "<extension UUID>",
    "monitor"" "N",
    "ring_time": 15,
    "queue_members": [
      {
         "number": "7777777777",
         "priority": 1
      },
      {
         "number": "6666666666",
         "priority": 2
      }
    ]
 }

Parameters:

  • name: The name you want to give the queue. You can use this name later to retrieve the queue with a GET request.
  • caller_ID: The phone number to display as the caller ID for the queue phone number.
  • announcement: The resource ID for the greeting that callers hear when they reach the queue. Note that before you create your queue, you will need to identify the resource ID for the greeting you want to use by doing a GET /media request.
  • hold_music: The resource ID for the hold music that callers hear while waiting in the queue.
  • max_hold_time: The maximum number of seconds that a caller can be on hold before being routed to the destination defined in maxhold_forward_selector field.
  • max_forward_selector: The destination to which you want to route callers when the caller is on hold for longer than the maximum hold time. In the example above, callers will be routed to voicemail, but they can also be routed to an application configured in your account.
  • extension: The resource ID for the voicemail extension to which you want to route callers after the maximum hold time. Only set this parameter if the value for maxhold_forward_selector is voicemail. Note that before you create your queue, you will need to identify the resource ID for the voicemail extension you want to use by doing a GET /extensions request.
  • monitor: Activates call monitoring when set to Y.
  • ring_time: The number of seconds that a phone number in the queue will ring before the caller is transferred to the next queue member.
  • queue_members: The list of queue members, listed in an array, and including their phone numbers and priority (position) in the queue.

When you send this JSON object to the Phone.com API using a POST request to the /queues service, our system will generate the new queue, along with a resource ID for it. For a full list of queue parameters that can be defined in the object, see POST /queues.

Adding the Queue to Your Account

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

Then, add the JSON object describing your new queue:


 {
    "name": "<queue_name>",
    "caller_id": "<caller ID>",
    "announcement": "<greeting UUID>",
    "hold_music": "<hold music UUID>"
    "max_hold_time": 5,
    "maxhold_forward_selector": "voicemail",
    "extension": "<extension UUID>",
    "monitor"" "N",
    "ring_time": 15,
    "queue_members": [
      {
         "number": "7777777777",
         "priority": 1
      },
      {
         "number": "6666666666",
         "priority": 2
      }
    ]
 }

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);
      $queue_1 = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your queue is: $queue_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 queue, 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" : "079f2a3-d128-771a-e79d-c68878f5cb49"
     }
  }

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

Example: Success! The ID for your queue is: 079f2a3-d128-771a-e79d-c68878f5cb49

You can also log into your Phone.com API Developer account and locate the queue by name (click Configure > Queues > Manage Queues).


Manage Queues page

Success! You’ve created a new queue and retrieved the ID for it. You can now use your queue with other API objects—for example, you can specify it when setting up call routing or use it when building menus.

Copy the Code

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


  <?php

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

  $payload = <<<JSON
   {
      "name": "<queue_name>",
      "caller_id": "<caller ID>",
      "announcement": "<greeting UUID>",
      "hold_music": "<hold music UUID>"
      "max_hold_time": 5,
      "maxhold_forward_selector": "voicemail",
      "extension": "<extension UUID>",
      "monitor"" "N",
      "ring_time": 15,
      "queue_members": [
        {
           "number": "7777777777",
           "priority": 1
        },
        {
           "number": "6666666666",
           "priority": 2
        }
      ]
   }
  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) {
      $tmp = json_decode($result, true);
      $queue_1 = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your queue is: $queue_1<br>";
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
  }

  ?>

Learn More: