Using the API to Create a Text-to-Greeting Recording

The Phone.com API includes a /greetings service with a text-to-greeting feature that allows you to submit plain text, and have it converted to a recorded greeting. You can then use the recording, which is saved as a media object in your Phone.com API Developer’s account, in your menus and routes.

In this tutorial, we will create a text-to-greeting recording, add it to your account, and retrieve the resource ID of the recording.

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

Preparing Your Text-to-greeting Recording

First, we will construct the JSON object for your text-to-greeting file as follows:


 {
    "name": "<greeting name>",
    "type": "tts",
    "tts_voice": "<voice name>",
    "tts_text": "<text message>"
 }

Parameters:

  • name: The name you want to give to the greeting. You can use this name to retrieve the greeting later.
  • type: Must be set to tts (text-to-speech).
  • tts_voice: You can select one of many Phone.com automated voices for the transcoding. See POST /media for the full list of available voices.
  • tts_text: The text message that you want to convert to a greeting, including commas and periods to suggest pauses.

When you send this JSON object to the Phone.com API using a POST request to the /greetings service, our text-to-greeting service will generate your greeting using the voice you selected. For a full list of parameters that can be defined in the object, see POST /media.

Adding the Recording to Your Account

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

Then, add the JSON object with your text message:


  $payload = <<<JSON
  {
      "name": "<greeting name>",
      "type": "tts",
      "tts_voice": "<voice name>",
      "tts_text": "<greeting text>"
  }
  JSON;

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.

Note that a successful response will return an HTTP 200 OK code and include the resource ID (UUID) for your new recording, 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);
      $voicemail_greeting_1 = $tmp['results']['data'][0]['id'];
      echo "Success! The ID for your recording is: $voicemail_greeting_1\n";
  } 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 and create your text-to-greeting recording. 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 recording, adding it to your account. Your browser will also display a success message.

Example:
Success! The ID for your recording is: e980d823-f587-11e2-a026-eb13f7ef552c

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


Manage Greetings page

Success! You’ve created a text-to-greeting recording 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. Text-to-greeting recordings offer a powerful way to create greetings quickly or on the fly.

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>';

  $payload = <<<JSON
  {
      "name": "<greeting name>",
      "type": "tts",
      "tts_voice": "<voice name>",
      "tts_text": "<greeting text>"
  }
  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);
      $voicemail_greeting_1 = $tmp['results']['data'][0]['resource_id'];
      echo "Success! The ID for your recording is: $voicemail_greeting_1\n";
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
  }

  ?>

Learn More: