---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/chat/rest/media#article
headline: Media
description: API reference for the Programmable Chat Media resource. Learn how to upload, download, and attach media files to Chat Messages using the Twilio Media API.
url: https://www.twilio.com/docs/chat/rest/media
inLanguage: en
dateModified: 2026-06-25T22:35:25.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Media

> \[!CAUTION]
>
> Programmable Chat has been deprecated and receives no support. Twilio has turned its focus to the next generation of chat: [Twilio Conversations][]. Find out more about the [EOL process][].
>
> * To start a project, see [Conversations][].
> * To switch from Programmable Chat, see the [Migration Guide][] to learn about how to switch.

[Twilio Conversations]: /docs/conversations

[EOL process]: https://www.twilio.com/en-us/changelog/programmable-chat-end-of-life-notice

[Conversations]: /docs/conversations-classic

[Migration Guide]: /docs/conversations-classic/migrating-chat-conversations

The Media resource allows media files to be uploaded and downloaded. Media files can be attached to [Messages](/docs/chat/rest/message-resource) as part of the [Media Messaging](/docs/chat/media-support) feature.

## API Base URL

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

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

## Authentication

To authenticate requests to the Twilio APIs, Twilio supports [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). Use your *API key SID* as the username and your *API key secret* as the password. You can create an API key [in the Twilio Console](/docs/iam/api-keys/keys-in-console) or [using the API](/docs/iam/api-keys/key-resource-v1).

Learn more about [Twilio API authentication](/docs/usage/requests-to-twilio).

```bash
curl -G https://mcs.us1.twilio.com/v1/Services \
    -u $TWILIO_API_KEY:$TWILIO_API_KEY_SECRET
```

> \[!NOTE]
>
> The Twilio SDKs don't support the Media resource.

## Properties \[#properties]

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][account] responsible for this message.                                                                                                                                   |
| service\_sid  | The unique id of the [Service][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][channel] the [Message][message] this media instance was added to.                                                                                                        |
| message\_sid  | The unique id of the [Message][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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/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](user-resource) that uploaded the Media instance as part of a [Message][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

To upload a media file, send a `POST` request with the file as the request body:

```bash
POST /Services/{Chat Service SID}/Media

```

The Chat Service SID must be the Chat Service instance SID this Media instance will be used for.

Upload the media file itself as the content of the `POST`. Tools such as curl and other clients abstract this and let you pass a path with a "binary" or similar option. The request is sent as a `POST` with the following headers, and the body is the file itself.

### Headers

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

### Body

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

### Curl Example

```bash
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

```bash
GET /Services/{Chat Service SID}/Media/{Media SID}

```

[account]: /docs/iam/api/account

[message]: /docs/chat/rest/message-resource

[channel]: /docs/chat/channels

[service]: /docs/chat/rest/service-resource