Skip to contentSkip to navigationSkip to topbar
On this page

Media


(error)

Danger

Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here(link takes you to an external page).

If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.

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.


API Base URL

api-base-url page anchor

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

https://mcs.us1.twilio.com/v1

To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication(link takes you to an external page). Use your API key as the username and your API key's secret as the password. You can create an API key either in the Twilio Console or using the API.

Note: Twilio doesn't recommend using your Account SID and Auth Token in production. For local testing, you can use your Account SID as the username and your Auth token as the password. You can find your Account SID and Auth Token in the Twilio Console(link takes you to an external page).

Learn more about Twilio API authentication.

1
curl -G https://mcs.us1.twilio.com/v1/Services \
2
-u $TWILIO_API_KEY:$TWILIO_API_KEY_SECRET
(information)

Info

The Twilio Helper Libraries doesn't support the Media resource.


Each Media resource instance has these properties:

namedescription
sidA 34 character string that uniquely identifies this resource.
account_sidThe unique id of the Account responsible for this message.
service_sidThe unique id of the Service this message belongs to.
date_createdThe date that this resource was created.
date_updatedThe date that this resource was last updated. null if the message has not been edited.
channel_sidThe unique id of the Channel the Message this media instance was added to.
message_sidThe unique id of the Message this media instance was added to.
sizeThe size of the file this Media instance represents in BYTES
content_typeThe MIME type of the file this Media instance represents. Please refer to the MIME Types(link takes you to an external page) for a list of valid MIME types.
file_nameThe filename of the underlying media file as specified when uploaded
authorThe identity of the User that uploaded the Media instance as part of a Message
urlAn absolute URL for this media instance
linksLinks 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

createupload-a-new-media-resource page anchor
1
POST /Services/{Chat Service SID}/Media
2

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.

Headers

headers page anchor
namedescription / 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 -X "POST" -H "Content-Type: multipart/form-data" -F "media=@/path/to/media.jpg;type=image/jpeg" "https://mcs.us1.twilio.com/v1/Services/<chat_instance_sid>/Media/" -u "<acount_sid>:<account_secret>"

Retrieve a Media resource

retrieve-a-media-resource page anchor
1
GET /Services/{Chat Service SID}/Media/{Media SID}
2