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:
- You send an MMS with an image via Twilio.
- You send a WhatsApp message with an image via Twilio.
- 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.
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
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account associated with this Media resource. |
content_type
|
The default MIME type of the media, for example |
date_created
|
The date and time in GMT when this Media resource was created, specified in RFC 2822 format. |
date_updated
|
The date and time in GMT when this Media resource was last updated, specified in RFC 2822 format. |
parent_sid
|
The SID of the Message resource that is associated with this Media resource. |
sid
|
The unique string that identifies this Media resource. |
uri
|
The URI of this Media resource, relative to |
Fetch a Media resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media/{Sid}.json
Returns a single Media resource using one of several representations:
Default: content-type
Without an extension, the media is returned using the mime-type provided when the media was generated.
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485
Alternative: XML
Appending ".xml" to the URI returns a familiar XML representation. For example:
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.xml
<TwilioResponse>
<Media>
<Sid>ME557ce644e5ab84fa21cc21112e22c485</Sid>
<AccountSid>ACda6f1e11047ebd6fe7a55f120be3a900</AccountSid>
<ParentSid>MM8dfedb55c129dd4d6bd1f59af9d11080</ParentSid>
<ContentType>image/jpeg</ContentType>
<DateCreated>Fri, 17 Jul 2009 01:52:49 +0000</DateCreated>
<DateUpdated>Fri, 17 Jul 2009 01:52:49 +0000</DateUpdated>
<Uri>/2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.xml</Uri>
</Media>
</TwilioResponse>Alternative: JSON
Appending ".json" to the URI returns a familiar JSON representation. For example:
GET /2010-04-01/Accounts/AC.../Message/MM.../Media/ME557ce644e5ab84fa21cc21112e22c485.json
{
"sid": "ME557ce644e5ab84fa21cc21112e22c485",
"account_sid": "ACda6f1e11047ebd6fe7a55f120be3a900",
"parent_sid": "MM8ff928b2451c0db925bd2d581f0fba79",
"content_type": "image/jpeg",
"date_created": "Fri, 26 Apr 2013 05:41:35 +0000",
"date_updated": "Fri, 26 Apr 2013 05:41:35 +0000",
"uri": "/2010-04-01/Accounts/ACda6f1e11047ebd6fe7a55f120be3a900/Message/MM8dfedb55c129dd4d6bd1f59af9d11080/Media/ME557ce644e5ab84fa21cc21112e22c485.json"
}Parameters
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account associated with the Media resource. |
message_sid
Path
|
The SID of the Message resource that is associated with the Media resource. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Media resource to fetch. |
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.
Example 1
Read multiple Media resources
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.
Filter by date created
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:
Parameters
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that is associated with the Media resources. |
message_sid
Path
|
The SID of the Message resource that is associated with the Media resources. |
date_created
Optional
|
Only include Media resources that were created on this date. Specify a date as |
Example 1
Delete a Media resource
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.
Parameters
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that is associated with the Media resource. |
message_sid
Path
|
The SID of the Message resource that is associated with the Media resource. |
sid
Path
|
The unique identifier of the to-be-deleted Media resource. |
Example 1
Hints and Advanced Uses
- 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-cacheensures 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.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
