MMS message support

The Sinch SMS REST API supports MMS messages in some circumstances. Note that:

  • MMS support is currently only available in the US region
  • You must contact support in order to enable this functionality

Just as with standard SMS messages and message batches, you can send an MMS message or a batch of MMS messages, 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:

{}

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:

required
object (MediaBody)

The message content, including a URL to the media file

to
required
Array of strings <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

object (parameterObj)

Contains the parameters that will be used for customizing the message for each recipient.

Click here to learn more about parameterization.

type
string

MMS

Value: "mt_media"
delivery_report
string
Default: "none"

Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.

Enum Value Description
none

No delivery report callback will be sent.

summary

A single delivery report callback will be sent.

full

A single delivery report callback will be sent which includes a list of recipients per delivery status.

per_recipient

A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

… 1 more
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url
string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference
string [ 0 .. 2048 ] characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

feedback_enabled
boolean
Default: false

If set to true, then feedback is expected after successful delivery.

strict_validation
boolean
Default: false

Whether or not you want the media included in your message to be checked against Sinch MMS channel best practices. If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.

Receiving MMS messages

Incoming MMS messages, like SMS messages, produce callbacks and can be polled using an API call to List inbound messages.

Media attached to the incoming message will be uploaded to the Sinch-provided or customer-provided storage (you must contact support 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": {},
  • "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 support
  • 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
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.