Send a MMS message to end users trough the Sinch MM7 API. Read more.
Send MMS MT to end users
To send a multimedia message, you send an MT message as a submit request to Sinch and supply the multimedia message as the payload. When Sinch accepts your MT message, we respond to you with a success status using "SubmitRsp" response. This indicates that your message was accepted for delivery. It doesn't, however, indicate that your message was delivered to the device. If the MT message was received in error, we respond to you with a failure status using SOAP fault "RSErrorRsp" response.
Group Messaging, also referred to as Group Chat, is enabled by utilizing the displayOnly attribute within the number node. To send multimedia messages to multiple recipients, one recipient's displayOnly attribute must be set to false, while the others' attributes should be set to true. If the attribute is set to false for more than one recipient, the API request will be declined with Status code 2572. If it's set to true for all recipients, the request will be declined with Status code 2571. The attribute only accepts true or false, with false being the default setting. Please refer to the status code sections for more status-related information.
It's important to note that group messaging operates as a pass-through, ensuring delivery only to the recipient with the displayOnly attribute set to false. To ensure delivery to all recipients, multiple requests must be made for each recipient with the Number's displayOnly attribute set to false.
This feature is only available for Sinch 10DLC MMS offering for US Wireless carriers: AT&T, T-Mobile US, Verizon Wireless, U.S. Cellular, and Google Voice.
Using the mobile operator ID in an MM7 request - (Standard MMS Only)
You can supply the mobile operator details as an ID in the request header of an MM7 "SubmitReq" request. If you don't supply the mobile operator, Sinch would look it up (this may be a separately charged fee, depending on your contract). The same mobile operator ID is returned in the HTTP header of delivery reports and MO requests. For the best throughput performance, you should include the mobile operator ID in each request, otherwise an operator lookup is needed before we can forward the message to the mobile operator.
| Header Name | Description | Mandatory |
|---|---|---|
| X-Mblox-Carrier-Id | Sinch Mobile Operator ID. Examples: AT&T=0001470, Verizon=0001890. See all Sinch operator IDs. | No |
SMIL is Required
SMIL is required in all the SubmitReq MM7 Requests. SMIL is an XML based language to write interactive multimedia presentations. For more information about SMIL, see the World Wide Web Consortium's document on SMIL.
Supported MM7 SOAP envelope request elements
| Element | Description | Mandatory |
| TransactionID | The identification of the MM7 SubmitReq/SubmitRsp pair. It's located in,the SOAP header. You supply this in the MM7 SubmitReq and Sinch returns,it in the corresponding SubmitRsp. | Yes |
| SubmitReq | Identifies the message as an MMS MT submit. This is the message type for an MT request. | Yes |
| MM7Version | Identifies the MM7 Version.(Supported versions are ver-5.3.0 and ver-6.8.0) | Yes |
| VASPID | Sinch provides an API key after your account is provisioned which is your VASPID. | Yes |
| VASID | Your account manager will provide you with a VASID for each shortcode. It's mandatory for accounts using shared shortcodes, otherwise optional. | No |
| SenderAddress | This is your shortcode. Should be provisioned and configured to your account and service. | Yes |
| Recipients | The mobile phone number of the end user. This must be a valid mobile,number in international format without a leading + symbol; for example: 12515550123 (US) and 447700900750 (UK). Multiple numbers are NOT supported. | Yes |
| Subject | Title of the whole multimedia message. Recommended size is 80 characters. See the special considerations section for information on character restrictions. | No |
| Content | Content of the multimedia message. href:cid attribute links to attachment. | Yes |
| allowAdaptations | Indicates if you wish to allow the mobile operator to re-encode (transcode) the content to make the content more suitable to the target handset. Each mobile operator may choose to obey or ignore this field; for example, some mobile operators assume or require by default the,option to transcode content. AllowAdaptations is an attribute of Content element. The value must be Boolean (either true or false). The default is true. | No |
| DeliveryReport | A request for delivery report. Boolean value true/false. Defaults value is true. | No |
| ExpiryDate | The desired time of expiry for the MM (time stamp). Date format is absolute. Default value is 3 days. | No |
See unsupported elements for MM7_Submit.
Example
<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
<SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<MM7Version>6.8.0</MM7Version>
<SenderIdentification>
<VASPID>skfdjslkjfdslkfj434das</VASPID>
<VASID>126273</VASID>
<SenderAddress>
<ShortCode>111122</ShortCode>
</SenderAddress>
</SenderIdentification>
<Recipients>
<To>
<Number>16172383232</Number>
</To>
</Recipients>
<Subject>My first MM7 Message</Subject>
<Content allowAdaptations="false" href="cid:generic" />
</SubmitReq>
</soap-env:Body>
</soap-env:Envelope>Supported MM7 SOAP envelope response elements
| Element | Description |
| TransactionID | The identification of the MM7 SubmitReq/SubmitRsp pair. It's located in the SOAP header. You supply this in the MM7 SubmitReq and, Sinch returns it in the corresponding SubmitRsp. |
| SubmitRsp | Identifies the message as a MM7 Submit Response. This is the message type for an MT response. |
| MM7Version | Identifies the MM7 Version.(Supported versions are ver-5.3.0 and ver-6.8.0) |
| StatusCode | MT message submit accepted/rejected is based on Success/Failure status code. “Success” response doesn't mean the message was delivered to the handset. See all MMS status codes. |
| StatusText | Description of the status code. |
| MessageId | If the MT message submit's successful then this contains the Sinch generated ID of the submitted message. This ID is expected in the delivery reports relating to this message. |
Example: Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env:Header>
<TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
<SubmitRsp>
<MM7Version>6.8.0</MM7Version>
<Status>
<StatusCode>1000</StatusCode>
<StatusText>Successfully parsed and validated request</StatusText>
</Status>
<MessageID>369500617770864640</MessageID>
</SubmitRsp>
</soap-env:Body>
</soap-env:Envelope>Example: Failure
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env:Header>
<TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
<soap-env:Fault>
<faultcode>soap-env:Client</faultcode>
<faultstring>Client error</faultstring>
<detail>
<RSErrorRsp>
<MM7Version>6.8.0</MM7Version>
<Status>
<StatusCode>2007</StatusCode>
<StatusText>Unable to parse request</StatusText>
<Details>Message format corrupt</Details>
</Status>
</RSErrorRsp>
</detail>
</soap-env:Fault>
</soap-env:Body>
</soap-env:Envelope>Request:
POST /mm7/v1 HTTP/1.1
Authorization: Basic dW5pdmyc2FsLXZhcj2YWwtdmFzcC1wd2Q=
Host: api.Mblox.com
Accept: */*
Content-Type: multipart/related; boundary="mainBoundary"; type="text/xml"; start="<mm7-start>"
SOAPAction: "http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4"
Content-Length: 45454
X-Mblox-Carrier-Id: 0001890
Expect: 100-continue
--mainBoundary
Content-Type: text/xml; charset=utf-8
Content-ID: <mm7-start>
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" SOAP-ENV:mustUnderstand="1">555e29f8879be</TransactionID>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<SubmitReq>
<MM7Version>6.8.0</MM7Version>
<DeliveryReport>true</DeliveryReport>
<SenderIdentification>
<VASPID>spUsdstW2u6GbvnMOsdseXrBa7NNLwTdKL</VASPID>
<VASID>61295</VASID>
<SenderAddress>
<ShortCode>111122</ShortCode>
</SenderAddress>
</SenderIdentification>
<Recipients>
<To>
<Number>16179593069</Number>
</To>
</Recipients>
<Subject>My first MM7 Message</Subject>
<ExpiryDate>2015-05-24T18:54:48+00:00</ExpiryDate>
<TimeStamp>2015-05-21T18:54:48+00:00</TimeStamp>
<Content allowAdaptations="false" href="cid:generic_content_id"/>
</SubmitReq>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--mainBoundary
Content-Type: multipart/related; start="<mms.smil>";
boundary="subBoundary"; type="text/xml"
Content-ID: <generic_content_id>
--subBoundary
Content-Type: text/plain; charset=utf-8
Content-ID: <132c4ca56a209475>
MM7 Test Text
--subBoundary
Content-Type: application/smil; charset=utf-8
Content-ID: <mms.smil>
<?xml version="1.0" encoding="UTF-8"?><smil><head><layout><root-layout width="100%" height="100%"/><region id="Text" top="50%" left="0" height="50%" width="100%" fit="hidden"/></layout></head><body><par><text src="cid:132c4ca56a209475" region="Text"/></par></body></smil>
--subBoundary--
--mainBoundary--Response:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Mon, 16 Mar 2015 17:46:59 GMT
Server: Apache
Vary: Accept-Encoding,User-Agent
Content-Length: 715
Connection: keep-alive
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env:Header>
<TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
<SubmitRsp>
<MM7Version>6.8.0</MM7Version>
<Status>
<StatusCode>1000</StatusCode>
<StatusText>Successfully parsed and validated request</StatusText>
</Status>
<MessageID>369500617770864640</MessageID>
</SubmitRsp>
</soap-env:Body>
</soap-env:Envelope>The Subject parameter should not contain emoji/Unicode characters as this will cause messages to get rejected by the carrier's MMSC.
Additionally, the Subject parameter should not contain any of the following special characters: <, >,&, ', or ". Including any of these characters will cause the message to be rejected. Instead, use the XML character entity name, which will allow the character to display correctly in the message:
| Entity Name | Description | Rendered Text |
|---|---|---|
< | Less than | < |
> | Greater than | > |
& | Ampersand | & |
' | Single quotation mark (apostrophe) | ' |
" | Double quotation mark | " |