Rate this page:


We intend to sunset the Programmable Chat API on July 25, 2022 to focus on the next generation of chat: the Twilio Conversations API. Find out about the EOL process. We have also prepared this Migration Guide to assist in the transition from Chat to Conversations.

The Media resource allows media files to be uploaded and downloaded. Media files can be attached to Messages as part of the Media Messaging feature.

Note The Media REST resource is accessed via a separate sub-domain from Chat and other Twilio products. The base URL for Media is:


HTTP requests to the REST API are protected with HTTP Basic authentication like other REST APIs provided by Twilio. To learn more about how Twilio handles authentication, please refer to our security documentation. In short, you will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.

curl -G \

You can find your account SID and auth token in the admin console. Alternately, you can also use API keys and secrets to authenticate REST API requests - you can manage API key pairs in the console also.

Note: The Media endpoint is not represented in the Twilio Helper Libraries at this stage.


Each Media resource instance has these properties:

name description
sid A 34 character string that uniquely identifies this resource.
account_sid The unique id of the Account responsible for this message.
service_sid The unique id of the Service this message belongs to.
date_created The date that this resource was created.
date_updated The date that this resource was last updated. null if the message has not been edited.
channel_sid The unique id of the Channel the Message this media instance was added to.
message_sid The unique id of the Message this media instance was added to.
size The size of the file this Media instance represents in BYTES
content_type The MIME type of the file this Media instance represents. Please refer to the MIME Types for a list of valid MIME types.
file_name The filename of the underlying media file as specified when uploaded
author The identity of the User that uploaded the Media instance as part of a Message
url An absolute URL for this media instance
links Links to access the underlying media file (content) and a temporary URL to use to access this (content_direct_temporary)

Create/Upload a new Media resource

POST /Services/{Chat Service SID}/Media

Note that the Chat Service SID above must be the Chat Service instance sid this Media instance will be used for.

A number of options exist for the creation of media. The media file itself needs to be uploaded as content to the POST - although tools such as curl and other clients abstract this and allow a "binary" or similar option to be used, and then passing in only a path. An example of this follows:

Ultimately this will be converted into a POST request, with the following headers and the body being the file itself.


name description / value
Content-Type: Must be: multipart/form-data
Content-Size: The size of the media (the file) being uploaded in bytes


The body or content of the POST must be the file itself in binary format.

Curl Example

curl -X "POST" -H "Content-Type: multipart/form-data" -F "media=@/path/to/media.jpg;type=image/jpeg" "<chat_instance_sid>/Media/" -u "<acount_sid>:<account_secret>"

Retrieve a Media resource

GET /Services/{Chat Service SID}/Media/{Media SID}
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 Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more