Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Media Resource


The Media subresource of the Message resource represents a piece of media, such as an image, that is associated with a Message.

Twilio creates a Media resource and stores the contents of the media when the following events occur:

  1. You send an MMS with an image via Twilio.
  2. You send a WhatsApp message with an image via Twilio.
  3. You receive media in a message sent to one of your Twilio numbers or messaging channel addresses.

Twilio retains the stored media until you delete the related Media resource instance.

To secure access to media stored on Twilio, you can enable HTTP basic authentication in the Console settings for Programmable Messaging(link takes you to an external page).

(warning)

Warning

Messages sent via Twilio can include up to 10 media files that have a total size of up to 5MB. Twilio resizes images as necessary for successful delivery based on carrier specifications. Messages with over 5MB of media will not be accepted.


Media Properties

media-properties page anchor
account_sidSID<AC>
Not PII

The SID of the Account(link takes you to an external page) associated with this Media resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

content_typestring

The default MIME type(link takes you to an external page) of the media, for example image/jpeg, image/png, or image/gif.


date_createdstring<date-time-rfc-2822>

The date and time in GMT when this Media resource was created, specified in RFC 2822(link takes you to an external page) format.


date_updatedstring<date-time-rfc-2822>

The date and time in GMT when this Media resource was last updated, specified in RFC 2822(link takes you to an external page) format.


parent_sidSID<SM|MM>

The SID of the Message resource that is associated with this Media resource.

Pattern: ^(SM|MM)[0-9a-fA-F]{32}$Min length: 34Max length: 34

sidSID<ME>

The unique string that identifies this Media resource.

Pattern: ^ME[0-9a-fA-F]{32}$Min length: 34Max length: 34

uristring

The URI of this Media resource, relative to https://api.twilio.com.


GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{Sid}.json

Returns a single Media resource using one of several representations:

  • content-type
  • XML
  • JSON

Default: content-type

default-content-type page anchor

Without an extension, the media is returned using the mime-type provided when the media was generated.


_10
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485

Appending ".xml" to the URI returns a familiar XML representation. For example:


_10
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.xml


_11
<TwilioResponse>
_11
<Media>
_11
<Sid>ME557ce644e5ab84fa21cc21112e22c485</Sid>
_11
<AccountSid>ACda6f1e11047ebd6fe7a55f120be3a900</AccountSid>
_11
<ParentSid>MM8dfedb55c129dd4d6bd1f59af9d11080</ParentSid>
_11
<ContentType>image/jpeg</ContentType>
_11
<DateCreated>Fri, 17 Jul 2009 01:52:49 +0000</DateCreated>
_11
<DateUpdated>Fri, 17 Jul 2009 01:52:49 +0000</DateUpdated>
_11
<Uri>/2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.xml</Uri>
_11
</Media>
_11
</TwilioResponse>

Appending ".json" to the URI returns a familiar JSON representation. For example:


_10
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.json


_10
{
_10
"sid": "ME557ce644e5ab84fa21cc21112e22c485",
_10
"account_sid": "ACda6f1e11047ebd6fe7a55f120be3a900",
_10
"parent_sid": "MM8ff928b2451c0db925bd2d581f0fba79",
_10
"content_type": "image/jpeg",
_10
"date_created": "Fri, 26 Apr 2013 05:41:35 +0000",
_10
"date_updated": "Fri, 26 Apr 2013 05:41:35 +0000",
_10
"uri": "/2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.json"
_10
}

AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) associated with the Media resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

MessageSidSID<SM|MM>required

The SID of the Message resource that is associated with the Media resource.

Pattern: ^(SM|MM)[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<ME>required

The Twilio-provided string that uniquely identifies the Media resource to fetch.

Pattern: ^ME[0-9a-fA-F]{32}$Min length: 34Max length: 34
(information)

Info

Because the stored media URLs are useful for many external applications, they are public and do not require HTTP Basic Auth to access. This allows you to embed the URL in a web application without revealing your Twilio API credentials.

If you have a need to restrict access to media stored with Twilio, you can enable HTTP Auth in the Console settings. When you fetch your Message Media after enabling HTTP auth, you will be directed to a signed URL that is only valid for 4 hours.

You can make subsequent API requests for new short-lived URLs for your media at any time.

Fetch a Media

fetch-a-media page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.media('MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(media => console.log(media.contentType));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"content_type": "image/jpeg",
_10
"date_created": "Sun, 16 Aug 2015 15:53:54 +0000",
_10
"date_updated": "Sun, 16 Aug 2015 15:53:55 +0000",
_10
"parent_sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}


Read multiple Media resources

read-multiple-media-resources page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media.json

Returns a list of Media associated with your Message. The list includes paging information.

You may limit the list of Message Media to media created on a given date. Provide the following query string parameter to your API call:

AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) that is associated with the Media resources.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

MessageSidSID<SM|MM>required

The SID of the Message resource that is associated with the Media resources.

Pattern: ^(SM|MM)[0-9a-fA-F]{32}$Min length: 34Max length: 34
DateCreatedstring<date-time>

Only include Media resources that were created on this date. Specify a date as YYYY-MM-DD in GMT, for example: 2009-07-06, to read Media that were created on this date. You can also specify an inequality, such as StartTime<=YYYY-MM-DD, to read Media that were created on or before midnight of this date, and StartTime>=YYYY-MM-DD to read Media that were created on or after midnight of this date.


DateCreated<string<date-time>

Only include Media resources that were created on this date. Specify a date as YYYY-MM-DD in GMT, for example: 2009-07-06, to read Media that were created on this date. You can also specify an inequality, such as StartTime<=YYYY-MM-DD, to read Media that were created on or before midnight of this date, and StartTime>=YYYY-MM-DD to read Media that were created on or after midnight of this date.


DateCreated>string<date-time>

Only include Media resources that were created on this date. Specify a date as YYYY-MM-DD in GMT, for example: 2009-07-06, to read Media that were created on this date. You can also specify an inequality, such as StartTime<=YYYY-MM-DD, to read Media that were created on or before midnight of this date, and StartTime>=YYYY-MM-DD to read Media that were created on or after midnight of this date.


PageSizeinteger

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

Pageinteger

The page index. This value is simply for client state.

Minimum: 0

PageTokenstring

The page token. This is provided by the API.

Return the list of Media associated with your Message

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.media
_11
.list({limit: 20})
_11
.then(media => media.forEach(m => console.log(m.sid)));

Output

_24
{
_24
"end": 0,
_24
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json?PageSize=50&Page=0",
_24
"last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json?PageSize=50&Page=0",
_24
"media_list": [
_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"content_type": "image/jpeg",
_24
"date_created": "Sun, 16 Aug 2015 15:53:54 +0000",
_24
"date_updated": "Sun, 16 Aug 2015 15:53:55 +0000",
_24
"parent_sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}
_24
],
_24
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json?PageSize=50&Page=50",
_24
"num_pages": 1,
_24
"page": 0,
_24
"page_size": 50,
_24
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json?PageSize=50&Page=0",
_24
"start": 0,
_24
"total": 1,
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json?PageSize=50&Page=0"
_24
}


DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{Sid}.json

Deletes Media from your account.

If successful, returns HTTP 204 (No Content) with no body.

AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) that is associated with the Media resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

MessageSidSID<SM|MM>required

The SID of the Message resource that is associated with the Media resource.

Pattern: ^(SM|MM)[0-9a-fA-F]{32}$Min length: 34Max length: 34

SidSID<ME>required

The unique identifier of the to-be-deleted Media resource.

Pattern: ^ME[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete Media from your account

delete-media-from-your-account page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')
_10
.media('ME557ce644e5ab84fa21cc21112e22c485')
_10
.remove();

Hints and Advanced Uses

hints page anchor
  • Twilio attempts to cache the media file the first time it is used. This may add a slight delay in sending the message.
  • Twilio caches files when HTTP headers allow it (via ETag and Last-Modified headers). Responding with Cache-Control: no-cache ensures Twilio always checks if the file has changed, allowing your web server to respond with a new version or with a 304 Not Modified to instruct Twilio to use its cached version.

Rate this page: