Requesting DTMF on a Phone Call

Our /calls service will be available soon! Read about call features and functions below but please don't try them out just yet.

The Phone.com API’s /calls service allows you to make and interact with phone calls. Calls can be made in real time (synchronously or asynchronously), or scheduled for a future time.

In this tutorial, we will request a DTMF (Dual-tone multi-frequency signal) digit from a synchronous call. The request will send a message to the call requesting a button be pressed on the receiving end. Consider that your application might be interacting with a live person, and ask them to press a digit. The digit chosen is returned to your application in the response, and you can take action based on the choice.

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


Preparing Your Call Request

First, we will construct the JSON object for your request to the /calls service as follows:


{
    "commands": [
        {
            "get_dtmf": {
                "timeout": 15,
                "commands": [
                    {
                        "say": {
                            "text": "Please press 1 to continue.",
                            "voice": "allison"
                        }
                    }
                ]
            }
        }
    ]
}


Parameters:

  • commands: The PUT method for /calls accepts an array of call commands, and for this tutorial we will use the command get_dtmf. This command includes all the information needed to request DTMF input from the callee:
    • get_dtmf: Defines the parameters needed to request DTMF input
      • timeout: If no DTMF tones are detected within the timeout period, the command will fail.
      • commands: Array of commands. play and say are the only valid commands in the get_dtmf commands array.
        • say: Allows you to convert a text string to an audio message (text to speech). Parameters include text to define the text you want converted to audio, and voice to set the voice you want to use for the audio output. The default voice is allison. To preview the voices available, log into your Phone.com API Developer account, and click Configure > Add Greeting, and select Text to Greeting. Type a message and use the Select a voice menu to test various voices.

When you send this JSON object to the Phone.com API using a PUT request to the /calls service, the commands will be validated and processed by our API server, playing the say command text and then retrieving the any DTMF input entered by the callee.

Sending the Request

Now that you’ve prepared the JSON object containing your get_dtmf command, 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

  $call_id = '<resource ID for the call>';
  $url     = 'https://v1.api.phone.com/calls/' . $call_id;
  $app_key = '<your app key>';
  $app_pwd = '<your app password>';

Then, add the JSON object:


  $payload = <<<JSON
  {
      "commands": [
          {
              "get_dtmf": {
                  "timeout": 15,
                  "commands": [
                      {
                          "say": {
                              "text": "Please press 1 to continue.",
                              "voice": "allison"
                          }
                      }
                  ]
              }
          }
      ]
  }
  JSON;

And the cURL code to send your POST request:


  $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_CUSTOMREQUEST, "PUT");
  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) {

      $response = json_decode($result, true);
      $call_status = $response['results']['call']['status'];

      $dtmf  = $response['commands'][0]['result'];

      if( $call_status == 'ready' && $dtmf == '1' ) {
          echo "Success! The get_dtmf command received the dtmf tone: $dtmf\n";
      } else {
          echo "get_dtmf command received: " . $dtmf . "\n";
      }
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
      echo "we received an error: " . $error['response'] . "\n";
  }

  ?>

Note that a successful response will return an HTTP 200 OK code and include a JSON object containing information about your call. 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 typical /calls response will include information about the call and the status of any commands you sent.


  {
      "response": {
          "service": "calls",
          "call": {
                  "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
                  "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
                  "to": "12345678900",
                  "from": "12345678901",
                  "duration": 17,
                  "direction": "outbound",
                  "schedule_start": "2014-01-03T05:17:27",
                  "schedule_start_epoch": 1388726247,
                  "schedule_expire": "2014-01-03T05:32:27",
                  "schedule_expire_epoch": 1388727147,
                  "time_start": "2014-01-03T05:17:29",
                  "time_start_epoch": 1388726249,
                  "status": "ready"
          },
          "commands": [
              {
                  "command": "get_dtmf",
                  "status": 200,
                  "result": "1"
              }
          ]
      }
  }

You now have all the components you need to make a successful PUT request to /calls, and request and receive DTMF input on your call. 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 play your text-to-speech message on your call. If the callee enters DTMF input, your browser will also display a success message: Success! The get_dtmf command received the dtmf tone: 1

Congratulations! You’ve requested and processed DTMF input on a phone call using the /calls service. You can continue to interact with the call using additional PUT requests specifying the call’s resource ID, or you can use the DELETE method to end the call.

Copy the Code

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


  <?php

  $call_id = '<resource ID for the call>';
  $url     = 'https://v1.api.phone.com/calls/' . $call_id;
  $app_key = '<your app key>';
  $app_pwd = '<your app password>';

  $payload = <<<JSON
  {
      "commands": [
          {
              "get_dtmf": {
                  "timeout": 15,
                  "commands": [
                      {
                          "say": {
                              "text": "Please press 1 to continue.",
                              "voice": "allison"
                          }
                      }
                  ]
              }
          }
      ]
  }
  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_CUSTOMREQUEST, "PUT");
  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) {

      $response = json_decode($result, true);
      $call_status = $response['results']['call']['status'];

      $dtmf  = $response['commands'][0]['result'];

      if( $call_status == 'ready' && $dtmf == '1' ) {
          echo "Success! The get_dtmf command received the dtmf tone: $dtmf\n";
      } else {
          echo "get_dtmf command received: " . $dtmf . "\n";
      }
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
      echo "we received an error: " . $error['response'] . "\n";
  }

  ?>

Learn More: