Toll-Free MMS (Limited Availability)

Follow

Jason Sommerset

Updated

Table of Contents

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

How do I send a Toll-Free MMS?

How do I receive a Toll-Free MMS?

What is the maximum supported file size I can send?

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

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

What file types are supported?

What is the maximum number of attachments I can send?

What happens if I send an unsupported file type?

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

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

Is group messaging/group MMS supported?

Can I use this with Hosted Toll-Free numbers?

Does Toll-Free MMS automatically handle STOP and UNSTOP?

MMS Error Codes

 

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 request access to the Limited Availability program, please contact Bandwidth sales

 

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

See our V2 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 an error code: 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 from 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, 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

.jpg

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

No, SMIL 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 greater 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 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 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. If you attempt to send a message to an end-user who has opted-out, the end user won’t receive the message and you’ll be billed for the attempt. Unlike SMS, you will NOT receive back a message failed callback 4775 "Carrier Rejected due to user opt out" error message.  

 

MMS Error Codes

Below are the common MMS errors you may see with Toll-Free MMS. To see the full list of V2 HTTP error codes, see our developer docs.

Common MMS Error Code

Description

Notes

4410

Could not download media

Typically, the media can’t be downloaded because of a HTTP 4XX or 5XX error, or other error retrieving the image from the media web server. Check the media URL and try to access 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 is not 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. 


Still have questions? Open a ticket on the Bandwidth Support Center.

Article is closed for comments.