To send an <<glossary:[^>]*>> message to a mobile device, you’ll utilize MM7 protocol, the industry standard protocol for sending MMS messages. The MM7 protocol is a SOAP-based protocol.
Code with caution
SOAP-based protocols are highly dependent on formatting of your calls. If you are not familiar with SOAP calls, we recommend using cURL to make the call and using our executable code samples, and use these as a starting point to build your requests.
Authorization Header
Just like with the HTTP SMS protocols, sending an MMS message requires you to include basic authentication. This header must be present for all requests. For more information, please refer to the section on Authentication.
Custom Headers
In addition to the basics, Vibes protocol further customizes the MM7 experience with a few custom headers, which allow the user more security and customization in their MMS send.
Header | Description |
---|---|
X-Vibes-CarrierCode | The Vibes Carrier Code, if known, otherwise the carrier is looked up. |
X-Vibes-DlrCallbackUrl | The URL to which Delivery Reports should be sent. |
Delivery Report Request Options
The table below specifies how the Multimedia Message Service Center (MMSC) would process the various Delivery Report request options.
X-Vibes-DlrCallbackUrl Header Set | X-Vibes-DlrCallbackUrl Header Not Set | |
---|---|---|
Delivery ReportFlag Set to true | Delivery Reports will be requested from the carrier, and any final status report returned from the carrier is sent to the Callback URL. | Delivery Reports are requested from the carrier but no callbacks are sent to the client. |
Delivery ReportFlag Set to false | The status of delivery of the message to carrier is returned to the Callback URL. Delivery Reports are not requested from the carrier. | Delivery reports are not requested from the carrier and no callbacks are sent to the client. |
Requests and Responses
The request body has a maximum total size of 1 MB. Requests with larger bodies will result in a 413 Entity Too Large error. Note that due to MIME/base64 encoding the request body will be larger than the binary media. File size can also affect performance; we recommend requests under 300 KB. Vibes supports MM7 protocol for multiple versions of MM7, so be sure you’re referencing the correct MM7 version before you get started.
Request
Below is an example of an XML call that uses the MM7 SOAP protocol to send a message with a gif attachment. The elements are defined below. CHOOSE YOUR MM7 VERSION BY SELECTING THE CORRESPONDING TAB ABOVE
POST /mms/mm7/submit HTTP/1.1
SOAPAction:
Authorization: Basic Y2xpZW50QHZpYmVzLmNvbTpwYXNzd29yZA==
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 127.0.0.1:8081
Content-Length: 47384
Content-Type: multipart/related; type="text/xml"; boundary=MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c; start="<[email protected]>"
X-Vibes-CarrierCode: 102
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-ID: <[email protected]>
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
<ns3:SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
<ns3:MM7Version>5.3.0</ns3:MM7Version>
<ns3:SenderIdentification>
<ns3:SenderAddress>
<ns3:ShortCode>63901</ns3:ShortCode>
</ns3:SenderAddress>
</ns3:SenderIdentification>
<ns3:Recipients>
<ns3:To>
<ns3:Number>+13127536330</ns3:Number>
</ns3:To>
</ns3:Recipients>
<ns3:DeliveryReport>true</ns3:DeliveryReport>
<ns3:Subject>Hello Vibes</ns3:Subject>
<ns3:Content href="cid:attachment.cid"/>
</ns3:SubmitReq>
</soapenv:Body>
</soapenv:Envelope>
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: multipart/mixed; boundary="----=_Part_1_735700397.1414682699327"
Content-Transfer-Encoding: binary
Content-ID: <attachment.cid>
------=_Part_1_735700397.1414682699327
Content-Type: image/gif; name=sample.gif
Content-Disposition: attachment; filename=sample.gif
Content-ID: <sample.gif>
GIF89aÔÔ ...
------=_Part_1_735700397.1414682699327
Content-Type: text/plain; name=Simple.txt
Content-Disposition: attachment; filename=Simple.txt
Content-ID: <Simple.txt>
Simple text as an attachment ...
------=_Part_1_735700397.1414682699327--
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c--
```xml MM7 6.8.0
POST /mms/mm7/submit HTTP/1.1
SOAPAction:
Authorization: Basic Y2xpZW50QHZpYmVzLmNvbTpwYXNzd29yZA==
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 127.0.0.1:8081
Content-Length: 47384
Content-Type: multipart/related; type="text/xml"; boundary=MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c; start="<[email protected]>"
X-Vibes-CarrierCode: 102
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-ID: <[email protected]>
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
<ns3:SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
<ns3:MM7Version>6.8.0</ns3:MM7Version>
<ns3:SenderIdentification>
<ns3:SenderAddress>
<ns3:ShortCode>63901</ns3:ShortCode>
</ns3:SenderAddress>
</ns3:SenderIdentification>
<ns3:Recipients>
<ns3:To>
<ns3:Number>+13127536330</ns3:Number>
</ns3:To>
</ns3:Recipients>
<ns3:DeliveryReport>true</ns3:DeliveryReport>
<ns3:Subject>Hello Vibes</ns3:Subject>
<ns3:Content href="cid:attachment.cid"/>
</ns3:SubmitReq>
</soapenv:Body>
</soapenv:Envelope>
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: multipart/mixed; boundary="----=_Part_1_735700397.1414682699327"
Content-Transfer-Encoding: binary
Content-ID: <attachment.cid>
------=_Part_1_735700397.1414682699327
Content-Type: image/gif; name=sample.gif
Content-Disposition: attachment; filename=sample.gif
Content-ID: <sample.gif>
GIF89aÔÔ ...
------=_Part_1_735700397.1414682699327
Content-Type: text/plain; name=Simple.txt
Content-Disposition: attachment; filename=Simple.txt
Content-ID: <Simple.txt>
Simple text as an attachment ...
------=_Part_1_735700397.1414682699327--
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c--
### Elements & Attributes of a Request
## Response
**Success**
CHOOSE YOUR MM7 VERSION BY SELECTING THE CORRESPONDING TAB ABOVE
```xml MM7 5.5.0
<?xml version=“1.0” encoding=“UTF-8"?>
<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/”>
<soapenv:Header>
<TransactionID xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>
<ns3:SubmitRsp xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>
<ns3:MM7Version>5.3.0</ns3:MM7Version>
<ns3:Status>
<ns3:StatusCode>1000</ns3:StatusCode>
<ns3:StatusText>Success</ns3:StatusText>
</ns3:Status>
<ns3:MessageID>d95c7ccb-4fbd-4b48-b70c-fadc5ff225b5</ns3:MessageID>
</ns3:SubmitRsp>
</soapenv:Body>
</soapenv:Envelope>
```xml MM7 6.8.0
<?xml version=“1.0” encoding=“UTF-8"?>
<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/”>
<soapenv:Header>
<TransactionID xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>16d105f4-9b86-4b8a-bdf5-9b02e2795fd6-1</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>
<ns3:SubmitRsp xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>
<ns3:MM7Version>6.8.0</ns3:MM7Version>
<ns3:Status>
<ns3:StatusCode>1000</ns3:StatusCode>
<ns3:StatusText>Success</ns3:StatusText>
</ns3:Status>
<ns3:MessageID>57df0722-28f1-49e9-aa85-626919b5b888</ns3:MessageID>
</ns3:SubmitRsp>
</soapenv:Body>
</soapenv:Envelope>
**Error**
CHOOSE YOUR MM7 VERSION BY SELECTING THE CORRESPONDING TAB ABOVE
```xml MM7 5.5.0
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">16d105f4-9b86-4b8a-bdf5-9b02e2795fd6-1</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<ns3:SubmitRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<ns3:MM7Version>5.3.0</ns3:MM7Version>
<ns3:Status>
<ns3:StatusCode>2002</ns3:StatusCode>
<ns3:StatusText>SenderAddress value 'YOUR_SHORTCODE' invalid, Reason: Invalid SenderAddress</ns3:StatusText>
</ns3:Status>
</ns3:SubmitRsp>
</soapenv:Body>
</soapenv:Envelope>
```xml MM7 6.8.0
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">16d105f4-9b86-4b8a-bdf5-9b02e2795fd6-1</TransactionID>
</soapenv:Header>
<soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<ns3:SubmitRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<ns3:MM7Version>6.8.0</ns3:MM7Version>
<ns3:Status>
<ns3:StatusCode>2002</ns3:StatusCode>
<ns3:StatusText>SenderAddress value 'YOUR_SHORTCODE' invalid, Reason: Invalid SenderAddress</ns3:StatusText>
</ns3:Status>
</ns3:SubmitRsp>
</soapenv:Body>
</soapenv:Envelope>
### Elements of a Response