style {` .panel-gray{ background-color: #CEE9F9; padding: 10px 10px 5px 10px; color:#000000; text-align: center;max-width: 1100px; border-radius:4px;font-family: Gilroy-Regular, Helvetica, Arial, sans-serif; } `} Note: The MMS functionality of the Sinch REST SMS API is scheduled for deprecation. If you would like to gain access to MMS functionality through other products, we encourage you to explore the options listed on the [Sinch MMS Overview page.](/docs/mms/overview/) # 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](https://dashboard.sinch.com/account/details). 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](/docs/sms/api-reference/sms/batches/sendsms), 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](/docs/mms/bestpractices/) 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](/docs/mms/bestpractices/) For example, consider the following message, which includes media and text: ![Text media message](/assets/sms_card_message_crop.796ad4693f6749a3d3aa88966f7b13c51bc9e465c3c03f2649bdab13c9618364.c6cba068.png) In order to send this message, you would make a call to the SMS REST API's [batch send endpoint](/docs/sms/api-reference/sms/batches/sendsms) 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](/docs/sms/api-reference/sms/batches/sendsms) and the [Parameters and properties](#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](/assets/mms_media_message.0eaabbdbec6faaa934ec59192e37f12d521733c729f04b472ac7df2d02ee1ee9.88839cbf.png) 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](/docs/mms/bestpractices/) 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: ```json { "$ref": "#/components/schemas/Media", "components": { "schemas": { "MtDestination": { "type": "string", "description": "List of phone numbers and group IDs that will receive the batch.\n\n[More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628).", "format": "E.164", "examples": [ "+15551231234", "+15551256344" ] }, "MediaBody": { "type": "object", "description": "The message content, including a URL to the media file", "properties": { "subject": { "type": "string", "description": "The subject text", "example": "Media message from Sinch!", "maxLength": 80, "minLength": 0 }, "message": { "type": "string", "description": "The message text. Text only media messages will be rejected, please use SMS instead.", "example": "Your text message.", "maxLength": 2000, "minLength": 0 }, "url": { "type": "string", "description": "URL to the media file", "example": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png", "maxLength": 2048, "minLength": 0 } }, "required": [ "url" ] }, "parameterObj": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "description": "The key is the recipient's MSISDN that should have the `parameter_key` replaced with the value.\n\nIf key is `default`, then specified value is used as the fall-back value for omitted recipient phone numbers [MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628).", "maxLength": 1600 }, "description": "The name of the parameter that will be replaced in the message body. \n\nLetters A-Z and a-z, digits 0-9 and .-_ allowed." }, "propertyNames": { "description": "They key if name of the parameter (`parameter_key`) present within body to be customized", "pattern": "^[A-Za-z0-9_\\-.]+$", "type": "string", "maxLength": 16, "minLength": 1 }, "description": "Contains the parameters that will be used for customizing the message for each recipient. \n\n[Click here to learn more about parameterization](https://developers.sinch.com/docs/sms/resources/message-info/message-parameterization)." }, "DeliveryReportType": { "type": "string", "description": "Kind of delivery report", "enum": [ "none", "summary", "full", "per_recipient", "per_recipient_final" ], "x-enumDescriptions": { "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.", "per_recipient_final": "A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC." } }, "Media": { "type": "object", "description": "Only available in the US. Contact your account manager if you wish to send MMS.", "properties": { "to": { "type": "array", "format": "E.164", "description": "List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)", "example": [ "+15551231234", "+15551256344" ], "items": { "$ref": "#/components/schemas/MtDestination" }, "maxItems": 1000, "minItems": 1 }, "from": { "type": "string", "description": "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.", "example": "+15551231234" }, "body": { "$ref": "#/components/schemas/MediaBody" }, "parameters": { "$ref": "#/components/schemas/parameterObj" }, "type": { "type": "string", "description": "MMS", "enum": [ "mt_media" ], "x-enumDescriptions": { "mt_media": "MMS" } }, "delivery_report": { "$ref": "#/components/schemas/DeliveryReportType" }, "send_at": { "type": "string", "format": "date-time", "description": "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](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.\n" }, "expire_at": { "type": "string", "format": "date-time", "description": "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](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.\n" }, "callback_url": { "type": "string", "description": "Override the default callback URL for this batch. Must be valid URL.", "maxLength": 2048, "minLength": 0 }, "client_reference": { "type": "string", "description": "The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch", "maxLength": 2048, "minLength": 0 }, "feedback_enabled": { "type": "boolean", "default": false, "description": "If set to `true`, then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery." }, "strict_validation": { "type": "boolean", "description": "Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](https://developers.sinch.com/docs/mms/bestpractices/).\nIf set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.\n", "default": false } }, "required": [ "body", "to" ], "title": "Media" } } } } ``` ## Receiving MMS messages Incoming MMS messages can be received in two ways: - [Retrieved by an API call](/docs/sms/api-reference/sms/inbounds/listinboundmessages). - [Received via webhooks](/docs/mms/mms-mo-postbacks/) 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. ## 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](https://dashboard.sinch.com/account/details) - 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