Open SidemenuDocs
Docs
Close Sidemenu

How to Upload & Store Media with the Telnyx APIhow-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 Media1--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 Meida 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.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.

Was this page helpful?