Menu

Expand
Rate this page:

SMS Media Resource

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

Twilio will create a Media resource and store the contents of the media when the following events occur:

  1. You send a message with an image via Twilio
  2. You receive media on one of your Twilio phone numbers

Twilio will keep that media around until you issue an HTTP DELETE on that instance.

To secure access to media stored on Twilio, you can enable HTTP basic authentication on 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 will resize 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
sid<AC> Not PII

The SID of the Account that created this Media resource.

content_type
string Not PII

The default mime-type of the media, for example image/jpeg, image/png, or image/gif

date_created
date_time<rfc2822> Not PII

The date and time in GMT that this resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that this resource was last updated, specified in RFC 2822 format.

parent_sid
sid<MM> Not PII

The SID of the resource that created the media.

sid
sid<ME> Not PII

The unique string that that we created to identify this Media resource.

uri
uri Not PII

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

Fetch a Media resource

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:

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
get sid<AC> Not PII

The SID of the Account that created the Media resource(s) to fetch.

message_sid
Path
get sid<MM> Not PII

The SID of the Message resource that this Media resource belongs to.

sid
Path
get sid<ME> Not PII

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 on media stored with Twilio, you can enable HTTP Auth on 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
Loading Code Sample...
        
        

        Fetch Media

        Read multiple Media resources

        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.

        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
        get sid<AC> Not PII

        The SID of the Account that created the Media resource(s) to read.

        message_sid
        Path
        get sid<MM> Not PII

        The SID of the Message resource that this Media resource belongs to.

        date_created
        Optional
        get date_time_inequality<iso8601> Not PII

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

        Example 1
        Loading Code Sample...
              
              
              Return the list of media associated with your message

              Read Media

              Return the list of media associated with your message

              Delete a Media resource

              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.

              Parameters
              Parameters in REST API format
              account_sid
              Path
              delete sid<AC> Not PII

              The SID of the Account that created the Media resource(s) to delete.

              message_sid
              Path
              delete sid<MM> Not PII

              The SID of the Message resource that this Media resource belongs to.

              sid
              Path
              delete sid<ME> Not PII

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

              Example 1
              Loading Code Sample...
                    
                    

                    Delete Media from your account

                    Hints and Advanced Uses

                    • Twilio will attempt to cache the media file the first time it is used. This may add a slight delay in sending the message.
                    • Twilio will cache files when HTTP headers allow it (via ETag and Last-Modified headers). Responding with Cache-Control: no-cache will ensure Twilio always checks if the file has changed, allowing your 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:

                    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.

                    Loading Code Sample...
                          
                          
                          

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif