Sending 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 send a DTMF (Dual-tone multi-frequency signal) digit to a synchronous call. This will simulate a digit being pressed on a telephone. Consider that your application might be interacting with a menu system that has asked you to press [5].

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": [
        {
            "send_dtmf" : {
                "dtmf": "5"
            }
        }
    ]
}


Parameters:

  • commands: The PUT method for /calls accepts an array of call commands, and for this tutorial we will use the command send_dtmf. This command includes all the information needed to send DTMF input on a call:
    • send_dtmf: Includes the DTMF tones you wish to send
      • dtmf: The DTMF tone or tones you want to send

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, sending the DTMF tone to the phone call. For a full list of parameters that can be defined in the object, see send_dtmf.

Sending the Request

Now that you’ve prepared the JSON object containing your send_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": [
          {
              "send_dtmf" : {
                  "dtmf": "5"
              }
          }
      ]
  }
  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_id = $response['results']['call']['resource_id'];
      $call_status = $response['results']['call']['status'];
      if( $call_status == 'ready' ) {
          echo "Success! The send_dtmf command was accepted by call id: $call_id\n";
      } else {
          echo "The send_dtmf command was not executed successfully, error: " . $response['commands'][0]['result'] . "\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 call object, 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 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": "send_dtmf",
                  "status": 200,
                  "result": "ok"
              }
          ]
      }
  }

You now have all the components you need to make a successful PUT request to /calls, and send a DTMF tone to 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 send the DTMF tone to the call. Your browser will also display a success message: Success! The send_dtmf command was accepted by call id: <resource ID of the call;

Congratulations! You’ve sent a DTMF tone to 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": [
          {
              "send_dtmf" : {
                  "dtmf": "5"
              }
          }
      ]
  }
  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_id = $response['results']['call']['resource_id'];
      $call_status = $response['results']['call']['status'];
      if( $call_status == 'ready' ) {
          echo "Success! The send_dtmf command was accepted by call id: $call_id\n";
      } else {
          echo "The send_dtmf command was not executed successfully, error: " . $response['commands'][0]['result'] . "\n";
      }
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
      echo "We received an error: " . $error['response'] . "\n";
  }

  ?>

Learn More: