Using the API to Upload a New Greeting

The Phone.com API includes a /media service that you can use to upload and manage recordings, including greetings and hold music.

In this tutorial, we will upload a new greeting to your account by making a POST request to the /media service. We will then retrieve the resource ID for the new greeting from your account.

Notes: There is no difference in format between a media file used as a greeting and one used for hold music. However, designating that a greeting can be used as hold music ensures that it appears in the appropriate drop-down menus (in your account settings) for setting hold music.

Be aware that you can also create a greeting using Phone.com’s Text-to-Greeting feature, available through the API. For more information, see Using the API to Create a Text-to-Greeting Recording.

In This Tutorial:

Prerequisites

To complete this tutorial, you will need:

  • A Phone.com API Developer account
  • Your application’s API key and password
  • Your audio file to upload (WAV, U-Law (G.711) or MP3 format). Note that the Phone.com /media service will convert your file to Mono CCITT U-Law format, sampled at 8000 samples per second (Normal Telephony Quality), and will normalize audio levels to full scale. For best results, please make sure that the files you upload are sampled at a 16-bit sample size. However, the original uploaded format will be available to download using the ?media=<format> argument.

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

Preparing Your Media Upload

First, we will construct the JSON object that describes the greeting upload as follows:


 {
    "name": "<greeting name>",
    "type": "file",
    "is_hold_music": "N",
 }

Parameters:

  • name: The name you want to give the greeting. You can use this name to retrieve the greeting later.
  • type: Must be set to file to indicate that this is a readymade greeting being added to your account, not a Text-to-Greeting upload (tts).
  • is_hold_music: Set to Y if you want to use this recording as hold music (played when callers are waiting in a queue) or N if this message will not be used as hold music. Note that you can also add greetings or hold music to your account using a POST request directly to the /greetings or /hold_music aliases. For a full list of greeting parameters that can be defined in the object, see POST /media.

When you send this JSON object to the Phone.com API using a POST request to the /media service, the file will be added to your Phone.com API Developer account as a greeting.

Adding the Greeting to Your Account

Now that you’ve prepared the JSON object describing your upload, 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. $sample_file holds the filepath and name of the media file that you want to upload. The file must be available in the directory specified, on your webserver. You can use a relative path to this directory, as long as the script has access permissions to the path.


  <?php

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

  $sample_file = "/path/to/sample.mp3";

Then, add the JSON object describing your upload. The @ symbol shown below provides error suppression on the file being uploaded.


  $payload = <<<JSON
   {
      "name": "<greeting name>",
      "type": "file",
      "is_hold_music": "N",
   }
  JSON;

  $payload['file'] = "@$sample_file";

Then add 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. Note that a successful response will return an HTTP 200 OK code and include the resource ID (UUID) for your new greeting, 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.


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

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

Example:
Success! The ID for your greeting is: 86c34fdd-ab59-91e2-t774-8263at1g72e7

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


Manage Greetings page

Success! You’ve uploaded a greeting and retrieved the ID for it. You can now use your greeting with other API objects—for example, you can assign it as the recording used to present a set of menu options, or you can define it in a call-control script as the recording to play when making a phone call. .

Copy the Code

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


  <?php

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

  $sample_file = "/path/to/sample.mp3";

  $payload = <<<JSON
   {
      "name": "<greeting name>",
      "type": "file",
      "is_hold_music": "N",
   }
  JSON;

  $payload['file'] = "@$sample_file";

  $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);
      $greeting_1 = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your greeting is: $greeting_1
"; } else { $error = array('http_code' => $info['http_code'], 'response' => $result); } ?>

Learn More: