How to Upload & Store Media with the Telnyx API

Our Media Storage API allows Telnyx users to handle media in their communications easier than ever before. Users can upload files directly to Telnyx via simple API commands, store them securely in our cloud environment, and serve them quickly and reliably in other Telnyx API actions. Files can be uploaded from your local machine, or from a publicly-accessible URL.

You can upload media by either specifying a publicly accessible Media URL or by using a multiport / data-form upload.

Note

Don't forget to update YOUR_API_KEY here.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
  "media_url": YOUR_MEDIA_URL
  }' \
  https://api.telnyx.com/v2/media

curl -X POST \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -F media=@YOUR_LOCAL_FILE_PATH \
  https://api.telnyx.com/v2/media

Response:

{
  "data": {
	  "created_at": "2021-06-29T08:47:39.765087Z",
	  "expires_at": "2021-07-01T08:47:37.173452Z",
	  "media_name": "ae6b8755-0543-4366-85aa-c28261d9174d",
	  "updated_at": "2021-06-29T08:47:39.765087Z"
  }
}

Both of the above methods support the ability to provide your custom, unique media_name in the request:

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{     	
    "media_url": YOUR_MEDIA_URL,
    “media_name”: “my-custom-unique-media-name”
  }' \
  https://api.telnyx.com/v2/media

Response:

{
  "data": {
    ...
	  "media_name": "my-custom-unique-media-name"
  }
}

You can now use the uploaded media in the Fax, Call Control REST API or TeXML scenarios.

The uploaded media can be used in fax API by following:

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{ 
    "media_name": "my-stored-media-name",
    "connection_id": "...",
    "from": “...”,
    “to”: “...”
    }' \
  https://api.telnyx.com/v2/faxes

If the media name given is invalid, then users will get an asynchronous webhook after they try to download the file:

{
  "event_type":"fax.failed",
  ... 
  "payload": {..., "failure_reason": "file_download_failed", ...}
}

The uploaded media can be used in the playback_start command in the following way:

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"media_name": "my-stored-media-name"}' \
https://api.telnyx.com/v2/calls/{call_control_id}/actions/playback_start

If the media name given is invalid, the error is synchronous, returned as a reply to the HTTP request:

HTTP status: 422
Error: 90039 “Invalid media name”

The following TeXML is returned when an inbound call is made:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Play mediaStorage="true">my-stored-media-name</Play>
</Response>

If the media name given is invalid, there will be no error handling.