Media

This guide walks through the available methods for managing Media using the Bandwidth Messaging API.

The Media resource lets you upload your media files to Bandwidth API servers so they can be used in applications without requiring a separate hosting provider.

note

You can upload files up to 3.75MB and file storage is free for an unlimited number of files. Files are stored for up to 48 hours. The API supports the Cache-Control header when you upload files.

Files you upload can only be accessed by you when you supply your API user's username and password - they are not available to anonymous users.

List Media Files

This operation returns a list of all the media files on your account.

Each request returns a maximum of 1000 media files.

Continuation-Token Header

Retrieving more than 1000 media files requires use of the Continuation-Token header. The Continuation-Token is returned in the response header, and can be included in another request in the request header to continue retrieving the subsequent media files.

The Continuation-Token does not need to be set for the 1st request.

Example

Request

GET https://messaging.bandwidth.com/api/v2/users/12345/media HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "contentLength": 561276,
    "mediaName": "{mediaName1}",
    "content": "https://messaging.bandwidth.com/.../media/{mediaName1}"
  },
  {
    "contentLength": 2703360,
    "mediaName": "{mediaName2}",
    "content": "https://messaging.bandwidth.com/.../media/{mediaName2}"
  },
  {
    "contentLength": 2257901,
    "mediaName": "{mediaName3}",
        "content": "https://messaging.bandwidth.com/.../media/{mediaName3}"
  }
]

Download a Media File

You MUST use your API username and password to download the media each and every time you want to access the file.

danger

We DO NOT recommend using Bandwidth's url to display/stream media files to your end-users. Providing your account id, username, and password to users' devices is a security risk, as they could use your credentials to access your account.

We recommend that you create a copy on your local server or a cloud storage service. Doing so allows you to specify your authentication method (if any) to keep your Bandwidth account and users safe.

Example

Request

GET https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{mediaId} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream

// The response body will be binary of your media

tip

For incoming media attachements, Bandwidth generates the media ID and provides the URL in the incoming-message webhook.

ex:

https://messaging.bandwidth.com/api/v2/users/{accountId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png

In these cases, the mediaId is everything after media/ in the URL.

mediaId = 14762070468292kw2fuqty55yp2b2/0/bw.png

Upload a Media File

This method uploads a file over HTTP. You may add headers to the request in order to provide some control to your media-file.

Bandwidth retains uploaded media for up to 48 hours.

If a file being uploaded has the same name as a file that already exists under that api account, the new file will overwrite the old file.

Example

Request

PUT https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{file.mp3} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: text/plain
Content-Length: 60

"@/filepath/file.mp3"

Response

HTTP 204 No Content

Delete a Media File

Example

Request

DELETE https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{file.mp3} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP 204 No Content