Rate this page:

Media Support in Conversations

Twilio Conversations supports media messages, allowing your users to add photos, video, and other file types to their conversation. The media display seamlessly between channels.

Remember that Chat-based participants are different from SMS- or WhatsApp-based participants in a Conversation.

This guide will cover sending and displaying media in the Chat-based portion of a Conversation using the client-side SDKs as well as using the REST Media Content Service (MCS) API.

Using Media Messaging with the client-side SDKs (iOS, Android and Javascript)

Creation of a media message for a Chat-based Conversations participant includes the following general steps, with details dependent upon the client platform:

  • Create a new message, passing in the media source and its mime content-type.
  • Optionally specify a default download filename to help your application display the media to other Conversation participants.
  • Programmable Chat provides feedback of the media upload progress, as well as an indication your media file has been successfully saved. (iOS and Android only)
  • The message is created in a specific Conversation and the Conversation Participants receive a notification.

When receiving a media message from a Conversation, your application will:

  • Receive a Conversation message that includes a media SID
  • When you're ready to display the media to your Chat-based user, you must obtain the download URL (Javascript) or call the download method, providing the location to save the media file (Android and iOS.)
  • Programmable Chat provides feedback as the download progresses and a completion call when the media file is ready.
  • Your client will display or otherwise make available the message's media content to the user.

Media on Conversation Messages are attachments and live separately from your Conversation message. A media SID associates the media file with its corresponding Conversation message.

Media files cannot exist without an owning message, and deletion of a message results in the cleanup of its associated media. Once created, media files are immutable; you can modify other supported attributes of a message that has media content, but the media itself is not changeable.

Platform Differences for Media Messaging

The media creation and download methods within the client-side SDKs take a stream or file as their parameter. How the media is expressed in the client-side SDK will depend on your platform:


For JavaScript, you can provide the following as the source for the new media message sent by a Chat-based Conversation Participant:

  • A new FormData object containing file information: filename, content-type, size, and all FormData-required information
  • A String or Node.js Buffer containing a media byte stream

When receiving a Conversation message, the media is accessible through a temporary URL. This URL is invalidated after 300 seconds. You can request a new temporary URL at any time.


Media files are uploaded by providing an NSInputStream-compliant stream to `TCHMessageOptions` for the new message. Likewise, you can provide any NSOutputStream as the destination for a media file download. These streams are often backed by a file, but they can just as easily live in memory, or pass through to a network connection.


For Android, you can provide any stream as the source for a new media message. Likewise, any can serve as the destination for a media file download. These streams are often backed by a file, but they can just as easily live in memory, or pass through to a network connection.

Creating a Media Message

Adding a media-enriched message to a Conversation is very similar to creating a new text-only message. You start by creating a message, but instead of `body` for the content, you provide a media file.


        Checking for Media Content

        Only Conversation messages which contain media will have a media SID associated with them. The code sample provided here shows how to detect a media message on each client-side platform.


              Retrieving Media Message Content

              It's important to note that at this time, Programmable Chat does not maintain an internal cache of media so you are encouraged to cache downloaded media in your application to avoid unnecessary downloads.


                    Using Media Messaging via the Conversations REST API

                    Your backend services can also add media to Conversations by uploading and attaching files to Conversations Messages. This section provides a brief overview of the typical Media flow using the REST API. For a more detailed API description, please refer to Conversations Media REST API documentation.

                    Note: Currently, Media Content Service (MCS) provides the underlying Media REST endpoint used to create (upload) the media (files). It is a separate endpoint and not supported in the Twilio Helper Libraries or the Twilio CLI.

                    Sending a Media Message

                    Sending a Media Message via the REST API is a two-step process:

                    1. First, upload the media file to Twilio's Media Content Service (MCS) via the REST API
                    2. Send a media message to the Conversation by attaching the media instance that you created in Step 1 to a new Conversation Message

                    Uploading media should be done directly from the source machine, using native HTTP facilities. Using cURL, the equivalent request looks like this:

                    curl -u “<account_sid>:<account_secret>” --data-binary “@<filename>”<chat_service_sid>/Media

                    The response to your POST request to create a Media instance via MCS contains a Media SID. You can attach the newly uploaded Media file to a Conversation message using that returned Media SID. You can consult the Conversation Message Resource documentation for more information about creating a new Conversation Message with the REST API that includes the media parameter.

                    curl -u "<account_sid>:<account_secret>" -X POST<conversation_sid>/Messages -d MediaSid=<media_sid>


                    Conversations is a cross-channel messaging product, so each channel has a different set of limitations about incoming media files. Please refer to the Media Limits documentation for channel-specific information and supported file types.

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