Twilio Programmable SMS supports sending picture messages (AKA MMS or multimedia messages) by adding the
MediaUrl parameter to your API request. Continue reading for more details on the supported file types, and attachment file size limitations.
For help with sending MMS messages, please see Simple Example for Sending Programmable SMS Text or Picture Messages.
Supported File Types
Twilio Programmable SMS supports
MediaUrl attachments with the following image file formats:
These image file types are supported by Twilio and will be formatted for delivery on destination devices.
Note: As of May 2021, there is an issue with Toll-Free MMS file size support; for these numbers you must ensure that any attachments (including images) are 600kb or smaller.
Twilio accepts a number of additional file formats as
MediaUrl attachments, but these file types are not formatted for destination device compatibility. For a full list of media formats accepted by the Twilio API, please see Accepted Content Types for Media (Twilio Docs)
Toll-Free MMS file size limitations
Toll-Free US numbers sending MMS to the US currently require all media attachments to be no larger than 600kb. This includes image files (jpeg, png, and gif). Twilio currently resizes these image file formats automatically, but a large image file might not be transcoded small enough to meet this 600kb limit when sent via a Toll-Free number. Twilio is working to remove this limitation.
MMS Message Size Limitations (for non-image messages via long code)
For file types other than jpeg, png and gif, the total file size limit for
MediaUrl attachments depends on the receiving carrier. Here are the attachment size limitations for MMS sent from either long code or short code numbers to the top 4 US-based carriers:
|Carrier||Long code MMS attachment size||Short code MMS attachment size|
|AT&T||0.675 MB||0.6 MB|
|Sprint||1.4 MB||1.4 MB|
|T-mobile||1.5 MB||1.0 MB|
|Verizon||0.675 MB||1.2 MB|
For other MMS-supported carriers, we recommend using attachments no larger than 600KB when sending files that are not jpeg, png, or gif images.
Twilio File Transcoding
Twilio will automatically transcode image file attachments in one of the supported file formats (jpeg, png, and gif). We will not transcode or resize any other types of media.
To ensure compatibility with all MMS-supported carriers, we recommend reducing the file size of any attachments with an "accepted" file type before attempting to send them.
If your media is not an image file and is larger than the limit shown above for the destination carrier, your MMS message will fail on Twilio with error 11751.
Number of attachments supported
Twilio supports up to 10
MediaUrl attachments, as long as the total size of the message body text and all attachments is less than 5 MB. An MMS message body can be up to 1600 characters long, which equals 4.8KB or roughly 1% of the total size limit.
If your message (including body text and media) is larger than 5 MB, your message request will fail.
Incoming MMS messages
There is no size limit for incoming MMS to your Twilio numbers. Twilio does not perform any transcoding or resizing on incoming media attachments, but the handset or sending carrier will likely apply transcoding before the file reaches Twilio.
In the rare case that an inbound MMS message contains more than 10 media attachments, Twilio's /Messages API will currently only surface the first 10 media attachments in the MediaUrl parameters. However, the Twilio Console will display all media attachments associated with that message record.
Typically, mobile handsets will restrict the number of attachments on an MMS message, or the total size of the message; because of this, messages with more than 10 attachments are uncommon.