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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

Response:

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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

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

Note: After pasting the above content, Kindly check and remove any new line added

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”

Note: After pasting the above content, Kindly check and remove any new line added

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>

Note: After pasting the above content, Kindly check and remove any new line added

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