MMS message support

The Sinch SMS REST API supports MMS messages in some circumstances. MMS support is currently available in the following destinations:

US
Canada
Australia
Puerto Rico

To enable MMS support in SMS, contact your account manager.

Just as with standard SMS messages and message batches, you can send an MMS message or a batch of MMS messages using the MediaRequest body, recieve corresponding callbacks, and poll for delivery reports related to those batches of MMS messages.

MMS best practices

This document provides general guidance for using the SMS API to send MMS messages. For more thorough recommendations and information on MMS support and constraints, see the Sinch MMS channel best practices documentation.

Sending MMS messages

The operation to send an MMS message, or a batch of MMS messages, has many of the same parameters and fields as the operation to send SMS messages. However, there are a few fields that require special attention when sending MMS messages using the SMS REST API:

The type field of the request must always be set to mt_media
You must always populate the url field of the body object. To include text with your media, populate the message field of the body as well
The strict_validation field, which is optional, allows you to enable message validation against Sinch MMS channel best practices

For example, consider the following message, which includes media and text:

Text media message

In order to send this message, you would make a call to the SMS REST API's batch send endpoint with the following payload:

{"from": "12345",
"to": ["15551231212"
],
"body": {"url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png",
"message": "Text message from Sinch!"
},
"type": "mt_media"
}

There are other optional objects and fields you can populate in the request as well. These are documented in both the API reference and the Parameters and properties section below.

Media support and constraints

Below are the supported media types and corresponding constraints for sending and receiving an MMS message using the SMS REST API:

image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
video: .mp4, .gif, .mov
vCard (Virtual Contact File): .vcf
PDF files: .pdf

We recommend you to keep media file sizes under 1MB as MMS providers usually use this limit.

The following image gives an example of a media message.

Media Message

Note that the above message includes media and no text. In this case, the body object does not include a populated message field.For more recommendations and information on MMS support and constraints, see the Sinch MMS channel best practices documentation.

Parameters and properties

The full list and description of the parameters and properties that can be included in the request body for sending a batch of MMS messages is below:

any (MediaRequest)

Receiving MMS messages

Incoming MMS messages can be received in two ways:

Media attached to the incoming message will be uploaded to the Sinch-provided or customer-provided storage (you must contact your account manager to have custom storage provisioned to your account) and the URL(s) to download the media will be returned. In the event of an error, an error code will be returned.

Note:

Any text content included in attached .txt files will be added to the message itself, rather than being included in a separate downloadable file.

{"body": {"subject": "Test subject",
"message": "Test message",
"media": [{"url": "https://some.s3.example.com/inbounds",
"contentType": "image/jpeg",
"status": "UPLOADED",
"code": 0
}
]
},
"from": "+11203494390",
"id": "01FC66621XXXXX119Z8PMV1QPA",
"received_at": "2019-08-24T14:15:22Z",
"sent_at": "2019-08-24T14:15:22Z",
"to": "11203453453",
"type": "mo_media"
}

Troubleshooting

If you run into an issue while using the SMS REST API to send MMS messages, ensure that:

You have MMS functionality enabled on your account. If do not, contact your account manager
All required fields are populated, including the url field in the body object
The type field is set to mt_media
The HTTP server that provides the media sets Content-Type in the header of the response
Downloading the media from that HTTP server takes less than 60 seconds