Toll-free MMS FAQ

If you’re a customer with access to Bandwidth’s toll-free MMS features, this support article will help you get started successfully. If you’d like to enable your account for toll-free MMS, please reach out to your Account Manager. Not sure who your Account Manager is? Please open a ticket with your Bandwidth Support Team or hit us up at (855) 864-7776!

Do I need to do anything special to configure my locations?

No. Once your account is enabled by your account manager, any location setup for HTTP messaging that you have added toll-free numbers on will have toll-free MMS enabled to send and receive. 

How do I send a toll-free MMS?

See our messaging developer docs for more information. The “from” number will be a toll-free number, but otherwise, the existing API is the same. For example, sending a picture message using our API looks like this:

POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {apiToken:apiSecret}

{
    "to"            : "+12345678902",
    "from"          : "+18XX5678901",
    "text"          : "Hey, check this out!",
    "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
    "media"         : [ "https://s3.amazonaws.com/bw-v2-api/demo.jpg"]
}

How do I receive a toll-free MMS?

Please see our messaging developer docs for more information. 

What is the maximum supported file size I can send?

The maximum size you can send outbound, including all attachments per MMS message, is 525KB.   

What if I attempt to send messages larger than 525KB?

If the total size of MMS message media/attachments exceeded 525KB, you’ll get a 4411 "rejected-message-size-limit-exceeded" callback error.

What is the maximum supported file size I can receive inbound?

Most operators have a maximum payload size of 1.5MB, but it may be larger depending on the handset and operator. Bandwidth doesn’t perform any transcoding or downsizing, however, some devices and even some carriers do transcode/compress inbound MMS.

For example, if you test a 10MB PNG file sent inbound to a toll-free number, it's received as 432KB on iPhone/AT&T, 172KB on iPhone/T-Mobile, 999KB on Android/T-Mobile, and 172KB on Android/Verizon. So, in general, expect a maximum of 1.5MB files inbound.    

What file types are supported?

Images, videos, audio, and text files are supported across all major U.S. wireless carriers and tested with iOS and Android devices/operating systems. While both the destination mobile operator and device ultimately determine compatibility, most mobile operators and handsets render the MMS file types specified here:

Content Type	Extension	Notes
audio/wav audio/x-wav	.wav	AT&T Note: For iOS, AT&T will transcode .wav files to .3gp audio files before delivering to handsets.
audio/ac3	.ac3
audio/amr	.amr
image/png	.png
image/jpeg	.jpeg
image/gif	.gif
image/bmp	.bmp
video/mp4	.mp4
video/x-msvideo	.avi	iOS and Android don’t support AVI natively. Although the file will be sent, it typically won't play on these device without third-party apps installed.
text/plain	.txt	Unlike other media types, the maximum .txt file size supported is 64KB per attachment.

What is the maximum number of attachments I can send?

The maximum number of attachments supported is 10. If you attempt to send more than 10 attachments, the POST /messages request will fail to be accepted and return a 400 Bad Request Error - "media must contain at most 10 media attachments." The total size of 10 attachments must still be 525KB or less.

What happens if I send an unsupported file type?

If you send an unsupported file type, it won’t be received on handsets. You also won’t receive an error message. For example, unsupported file types, such as PDF and vCards, which are under 525KB in total size, will be attempted to be sent and you’ll be billed for these attempts. It’s recommended to implement code to check for valid file types only.

Is SMIL a supported file type to control the content order?

SMIL may work intermittently but is not a supported file type for toll-free MMS.  

What is the maximum amount of text I can send with attachments?

For GSM-7, 1000 characters is the maximum recommended. For UCS-2 (e.g., using emojis), 500 is the maximum number of characters recommended. It’s possible to submit more than 1000 characters in the text field. We have tested over 2000 characters and, on most devices, it’s converted into a .txt attachment and the text is truncated in the native messaging app. Therefore, it’s recommended to keep the text under 1000 characters.  

Is group messaging/group MMS supported?

No. Group messaging isn’t supported on toll-free MMS. If you attempt to send a group MMS, you’ll receive a message-failed callback with error code 4435 "forbidden-too-many-recipients".

Can I use this with hosted toll-free numbers?

Yes. Toll-free MMS works with both hosted toll-free numbers and new toll-free numbers that are either provided by Bandwidth or ported to us.

Does toll-free MMS automatically handle STOP and UNSTOP?

Yes, please see our support article on how STOP and UNSTOP/START commands are handled at the network layer. Toll-free SMS and MMS use the same opt-out network layer filtering. If an end-user responds with STOP, the message will be sent inbound to the number as a toll-free SMS.

Note: If you attempt to send a message to an end-user who has opted out, they won’t receive the message and you’ll be billed for the attempt. Unlike SMS, you won't receive back a message failed callback 4775 "Carrier Rejected due to user opt out" error message.  

What are the common error codes?

Below are the common MMS errors you may see with toll-free MMS. For the full list of HTTP error codes, please see our developer docs.

Note: Bandwidth now supports MMS Delivery Receipts (DLRs), so you'll see Carrier Reported Client Errors in addition to the Bandwidth Reported Client Errors below.

Error Code	Description	Notes
4410	Could not download media	Typically, the media can’t be downloaded because of an HTTP 4XX or 5XX error, or other error retrieving the image from the media web server. Check the media URL and try to access it directly to see if the media can be fetched successfully.
4411	Combined size of media too large	The total size of MMS message media/attachments exceeded the max file size of 525KB.
4433	Messaging on toll-free number forbidden	Your account isn’t enabled for toll-free MMS or the destination TN isn't enabled for toll-free MMS.
4435	Too many recipients	Group messaging isn’t supported on toll-free MMS. If you attempt to send a message to more than one recipient, you’ll receive a "message-failed" callback with error code 4435 "forbidden-too-many-recipients".
5999	Unknown error processing message	This can happen when more than 1 attachment is being sent, but 1 or more of the attachments can’t be accessed. This can also happen when Bandwidth is unable to retrieve a single media/attachment from the media URL that was hosted on Bandwidth v2/../../media but has been deleted after 48 hours, so you’ll get this error instead of a 4410 error.