Skip to main content

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.

1. Upload Media​

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

Method 1: Specify a publicly accessible Media URL in the API​

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

Method 2: Multipart / form-data upload​

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"
  }
}

2. Using the uploaded media​

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

Fax​

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", ...}
}

Call Control REST API​

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”

TeXML​

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.

On this page​