Managing Media Files

The Phone.com API /media service lets you create (POST), retrieve a list (GET), update (PUT) and delete (DELETE) media files. These media resources can be used as announcements for queues, outgoing messages for menus, voicemail announcements, hold music, or can be played on connected telephone calls for various purposes. You can use the Phone.com API to accomplish all of these tasks. Below you will find guidelines to help you manage these resources successfully.

In This Topic:


Media Upload Formats and Limits

You can upload media files using a POST request to the /media service, which accepts file uploads in the following formats:

Note that our /media service will convert the files you upload to Mono CCITT U-Law format, sampled at 8000 samples per second (normal telephony quality), and will normalize the file audio levels to full scale. For best results please make sure 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 using your original format for the value.

Our /media service accepts files as multipart form uploads using the header:

Content-Type: multipart/form-data

The service expects the multipart form post to contain a portion consisting of a JSON body. This portion should be named data and should look similar to the following:


-------------d51608e2060ee4a09812218a1ad3249f

Content-Disposition: form-data; name="data"

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

Where - - - - - - - - - - - - -d51608e2060ee4a09812218a1ad3249f is the boundary deliminator.

The file portion of the post should contain the binary data of the file itself. It should be named file and should look similar to the following:


-------------d51608e2060ee4a09812218a1ad3249f

Content-Disposition: form-data; name="file"; filename="filename.ulaw"
Content-Type: application/octet-stream
<binary file data>
...

Notice that the file portion of the upload specifies the Content-Type header application/octet-stream and also includes the file name.

The complete request should look similar to the following example:


  Content-Type: multipart/form-data; boundary=-----------d51608e2060ee4a09812218a1ad3249f
  Authorization: Basic JasdfHhjhjyuialsdf768=

  -------------d51608e2060ee4a09812218a1ad3249f
  Content-Disposition: form-data; name="data"

  {
      "name":"<filename>",
      "type": "file",
      "is_hold_music":"N"
  }
  -------------d51608e2060ee4a09812218a1ad3249f
  Content-Disposition: form-data; name="file"; filename="filename.ulaw"
  Content-Type: application/octet-stream
  <binary file data>
  -------------d51608e2060ee4a09812218a1ad3249f--

  

Note that the bigger the file you upload the longer the upload request will take. The maximum size of the upload is 20MB. This limit includes the entire request and not just the binary file data.

Requesting A Media File As Binary Data

The Phone.com API /media service allows you to request a media file’s binary stream by specifying the ?media=<format> argument on the query string as follows:

https://v1.api.phone.com/media/8b2e034d-886e-11e3-907e-dc4da6eddaac?media=mp3

It is important to note that uploading a file in one format and then requesting it in another format can result in a lower quality recording then if you request the original file. This is because the /media service must transcode the original file into the requested format. For instance, if you upload a U-Law file sampled at 8000 samples per second with a 16-bit sample size and then request the file in MP3 format, the outcome may be a lower quality recording then the original U-Law file.

Requesting Media by Name Versus Resource ID

It is possible to request (GET) your media resources using the ?name=<name> query string argument as well as by resource ID. For example, both of the following requests are valid:

https://v1.api.phone.com/media/ba39253a-5635-11e3-9efc-eac0e6ed6a08
https://v1.api.phone.com/media/?name=voicemail_greeting_1

Keep in mind that GET requests by resource ID are returned as a single object, but requests by name are returned as an array of objects. This is because the /media service cannot guarantee that a resource name is unique. For this reason, it is typically better to note the resource ID for your object in your application logic or persistent storage.

Request and Response by Name:


          https://v1.api.phone.com/media/?name=voicemail_greeting_1
          {
             "response" : {
                "data" : [
                   {
                      "resource_id" : "3b7ec1af-9353-11e3-999e-c0c412a59a1c",
                      "create_date" : "2014-02-11T19:32:24",
                      "created_date_epoch" : "1392147144",
                      "duration" : "1",
                      "filename" : "",
                      "is_hold_music" : "false",
                      "is_temporary" : "false",
                      "name" : "voicemail_greeting_1",
                      "notes" : "",
                      "origin" : "tts",
                      "tts_text" : "Leave a message at the beep.",
                      "tts_voice" : ""
                   }
                ]
             }
          }

Request and Response by Resource ID:


          https://v1.api.phone.com/media/3b7ec1af-9353-11e3-999e-c0c412a59a1c

          {
             "response" : {
                "data" : {
                   "resource_id" : "3b7ec1af-9353-11e3-999e-c0c412a59a1c",
                   "create_date" : "2014-02-11T19:32:24",
                   "created_date_epoch" : "1392147144",
                   "duration" : "1",
                   "filename" : "",
                   "is_hold_music" : "false",
                   "is_temporary" : "false",
                   "name" : "voicemail_greeting_1",
                   "notes" : "",
                   "origin" : "tts",
                   "tts_text" : "Leave a message at the beep.",
                   "tts_voice" : ""
                }
             }
          }

Learn More: