Sending an MMS Notification using HTTP

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

This page describes how to send an MMS notification through the SMS Gateway. For information about integrating with the SMS Gateway, see either Sending a Single SMS or Broadcasting an SMS.

How an MMS notification is displayed to an end user is dependent on the cell phone. For example, some cell phones may clip or not show the address of the sender (specified by the mms_from parameter). Depending on the cell phone's settings, once a cell phone has received an MMS notification it may automatically download the MMS content or just notify the end user.

MMS Notifications are sent as binary data to the carrier. Each binary SMS message has a character limit of up to 140 characters before the message must be split. The character length of the following parameters are included in the character limits:

   mms_messagelocation
   mms_transaction_id
   mms_from
   mms_subject

To ensure that the MMS Notification does not require multiple SMS messages, make these parameters as short as reasonably possible.

You can use the MX Telecom MMS Gateway to send and receive MMS messages directly. For more information, see MMS Gateway.

Sending an MMS notification

Single-recipient end points:

     http://sms.openmarket.com/sms/v1/send
     https://sms.openmarket.com/sms/v1/send

Broadcast end points: (HTTP POST only)

     http://sms.openmarket.com/sms/v1/bulksend
     https://sms.openmarket.com/sms/v1/bulksend

Example single-recipient request:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4sSw0rD&smsto=12515550100&mms_messagelocation=http%3A%2F%2Fexample.com%2F123456&mms_expire=1440&mms_messageclass=80&mms_notification=1&mms_version=1.0&mms_from=%2B12515550145%2FTYPE%3DPLMN&mms_transaction_id=654321&mms_subject=Test%20MMS&mms_messagesize=35000

This sends an MMS notification to the number 12515550100. The mms_messagelocation parameter tells the cell phone to collect the MMS content from http://example.com/123456. The mms_expire parameter sets the message to expire after 24 hours.

Mandatory parameters:

ParameterDescription
user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 12515550100). No leading "+" is required.
If you are sending a broadcast SMS request, separate each MSISDN with a line break (e.g. smsto=12515550100%0A12515550123%0A12515550145).
mms_expireThe length of time, in minutes, that the message will be available. Setting an expiry time ensures that you do not need to host content indefinitely. However, individual cell phones may ignore this value and may use another expiry value. There is no defined maximum value for this parameter. The minimum value is 1 (1 minute).
mms_messageclassThe "message class", as per the MMS specification. This enables some cell phones to filter messages based on their class (for example, to ignore any MMS notification where class=81). There is currently no specific regulatory requirements for setting the MMS message type.
80 Personal
81 Advertisement
82 Informational
83 Auto
mms_messagelocationThe URI of the location hosting the MMS content. This must start with http://. For maximum compatibility with different cell phones, do not use HTTPS.
mms_messagesizeThe full size of message in bytes. This is passed to the cell phone so that it can display the file size to the end user before they download the file. The cell phone should not reject the message if this size is not exactly the same as the file itself.
mms_notificationThis identifies to the SMS Gateway that the request is for an MMS Notification. You must set this to 1.
mms_transaction_idA unique ID generated by your platform to identify the notification request when the cell phone retrieves the MMS content. This ensures that the platform can deliver dynamic content for each MMS notification sent. This can be an alphanumeric string.
mms_versionSpecifies the MMS specification version number. Currently there is only one version supported, version 1.0. You must set this parameter to 1.0.

Optional parameters specific to this request type:

ParameterDescription
mms_fromSets an originator for the MMS notification that is displayed to the end user before the MMS message is downloaded. You can set this to any value; however, long values may be clipped by the cell phone. Some cell phones may not show this value at all.
The value can be a number or email address, in one of these formats:
  +12515550145/TYPE=PLMN
  222111/TYPE=PLMN
  yourbusiness@example.com
Some cell phones may overwrite this with the value of the smsfrom field delivered with the MMS content.
Default: no default
mms_subjectThe subject line displayed to the end user for the MMS notification. This can be an alphanumeric string.
Default: no default

Carrier-specific parameters and requirements:

Where possible, OpenMarket removes the complexity of sending messages to multiple carriers. However, there are several carriers where you services may need to provide additional parameters or use a different messaging workflow. For information on these, please see US Carrier-Specific Requirements. The specific parameters are:

Optional parameters you can use for any request type:

  • smsfrom: sets the originator for the message—this parameter is mandatory for standard rate messages in all regions bar the US
  • submitid: used to send broadcast SMS messages
  • report: sets the delivery reports you want for the message
  • response: (for single-recipient requests only) changes the format of the HTTP response from the SMS Gateway
  • note, subaccount: optional reporting notes that you can add to the request
  • vp, billingsingleshot: alters the validity period and billing for the SMS message