MMS RESTful API

MMS RESTful API

February 21, 2013

The OneAPI MMS interface allows a Web application to send and receive MMS messages.

This is version 1 of the API. Document last published May 23rd 2012

Resources and URIs

OneAPI Location may be accessed via a RESTful API (this document) or via a more complex SOAP API (see OneAPI SOAP at www.gsmworld.com/oneapi). A RESTful API utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state.

POST, GET and DELETE are used in OneAPI MMS. The URIs of the resources are:

Sending MMS:

http://example.com/{api version}/messaging/outbound/{senderAddress}/requests

  • Send an MMS message to one or more mobile terminals

http://example.com/{api version}/messaging/outbound/{senderAddress}/requests/{requestId}/deliveryInfos

  • Query the delivery status of the MMS identified by requestId

http://example.com/{api version}/messaging/outbound/{senderAddress}/subscriptions

  • Start subscribing to delivery status notifications for all your sent MMS

http://example.com/{api version}/messaging/outbound/{subscriptionID}

  • Stop a subscription

Receiving MMS:

http://example.com/{api version}/messaging/inbound/registrations/{registrationId}/messages

  • Retrieve MMS sent to your Web application (which is identified by registrationId)

http://example.com/{api version}/messaging/inbound/subscriptions

  • Start and stop subscribing to notifications for MMS that have been sent to your Web application.

example.com is replaced by the hostname of the OneAPI server you are accessing. apiVersion optionally indicates the version of OneAPI MMS you are accessing – the default is the latest version supported by that server.

Request parameters

Please see the examples below for a description of the request parameters.

Representation formats

The MMS API supports application/x-www-form-urlencoded and application/JSON content types for POST operations. The response content type is application/JSON.

Encoding and Serialisation Details for MIME format

A MIME multipart message used in the MMS API consists of several parts:

  1. The root structure (e.g. InboundMMSMesssage or OutboundMMSMessage), expressed in JSON or form url-encoded format for requests. This part conveys the origin, destination addresses, subject, priority, message identifier, etc.
  2. The multimedia contents or attachments expressed in the form of links or as MIME body parts, within the HTTP request or response. They include all contents, both plain text as well as other MIME types (images, videos, etc), potentially exchangeable in MMSs.

For these messages with multiple body parts, multipart/form-data will be used instead as per RFC2388 and HTML FORMS. This means that:

  1. Root fields as described above will be included as a single form field with a MIME body with:
    • Content-Disposition: form-data; name=”root-fields”
    • Content-Type:
  2. Multimedia contents (text, images, etc.) will be included using one of the following two options:
    • When the message contains only one content; by including a MIME body with:
      • Content-Disposition: form-data; name=“attachments”, filename=”<name of the message content>”
      • Content-Type:
    • When the message contains more than one content; by including a form-field with a MIME body with:
      • Content-Disposition: form-data; name=“attachments”
      • Content-Type: multipart/mixed

      and then every one of the possible message contents included as subparts, using:

      • Content-Disposition:attachment; filename=”<name of the message content>”
      • Content-Type:
    • For every HTTP body part and subparts, it is possible to include other parameters (Content-Description, Content-Transfer-Encoding), etc.

The following section has examples of MIME multipart messages.

Examples : Sending Messages

Note the POST operations have been shown here as application/x-www-form-urlencoded. You can also use JSON in the request body, please see our Code libraries page for the code bindings.

Send an MMS from your Web application

POST http://example.com/1/messaging/outbound/tel%3A%2B12345678/requests HTTP/1.1
Content-Length: 12345
Content-Type: multipart/form-data;
                     boundary="===============123456==";

MIME-Version: 1.0
Host: www.example.com
Date: Thu, 04 Jun 2009 02:51:59 GMT

--===============123456==
Content-Disposition: form-data; name=”root-fields”
Content-Type: application/x-www-form-urlencoded;
address=tel%3A%2B13500000991&
address=tel%3A%2B13500000992&
senderAddress=tel:%2B12345678&
&senderName=Gameworld
Subject=My%20message&
notifyURL=http://example-application.com/notifications/
DeliveryInfoNotification/54311
&callbackData=
&clientCorrelator=123456
--===============123456==
Content-Disposition: form-data; name=”attachments”;
filename=”picture.jpg”
Content-Type: image/gif

GIF89a...binary image data...
--===============123456==--
Use POST to create the MMS. The senderAddress in the URL must be URL-escaped.
Mandatory parameters
Note: please see the section above ‘Encoding and serialisation for the MIME format’.
At least one address (URL-escaped end user ID) is required; in this case their MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+16309700001. OneAPI also supports the Anonymous Customer Reference (ACR) if provided by the operator.
Message (string) must be URL-escaped as per RFC 1738.
senderAddress (URL-escaped end user ID) is the address to whom a responding MMS may be sent
senderName(string) is the name to appear on the user’s terminal as the sender of the message.Optional parameters
clientCorrelator (string) uniquely identifies this create MMS request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid sending the same MMS twice.
notifyURL (anyURI) is the URL-escaped URL to which you would like a notification of delivery sent. The format of this notification is shown below.
callbackData (string) is any meaningful data you woul like send back in the notification, for example to identify the message or pass a function name, etc.

Successful response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/messaging/outbound/
tel%3A%2B12345678/requests/abc123
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"resourceReference": {"resourceURL":
" http://example.com/1/messaging/outbound/
tel%3A%2B12345678/requests/abc123"}}

201 shows that the message was created. The Location header field shows the URI of the created message, including the senderAddress and requestID(‘abc123’) in the path. You can append ‘/deliveryInfos’ to this URI to query the delivery status (see below).For convenience this URI is also included in the response body as the resourceURL pair within the resourceReference object.

Query the delivery status of an MMS

GET http://example.com/1/messaging/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos HTTP/1.1
Accept: application/json
Host: example.com:80

abc123 is the requestID which was returned in ‘create message’ response above.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"deliveryInfoList": {
    "deliveryInfo": [
        {
            "address": "tel:1350000001",
            "deliveryStatus": "MessageWaiting"
        },
        {
            "address": "tel:1350000999",
            "deliveryStatus": "MessageWaiting"
        }
    ],
    "resourceURL": " http://example.com/1/messaging/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos"
}}

The deliveryInfoList object contains the delivery information for each address that you asked to send the message to, in a deliveryInfoarray.The deliveryStatus value may be one of:

  • “DeliveredToTerminal”, successful delivery to Terminal.
  • “DeliveryUncertain”, delivery status unknown: e.g. because it was handed off to another network.
  • “DeliveryImpossible”, unsuccessful delivery; the message could not be delivered before it expired.
  • “MessageWaiting” , the message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
  • “DeliveredToNetwork”, successful delivery to the network enabler responsible for routing the MMS

The resourceURL is a reference to this response.

Subscribe to MMS delivery notifications

POST http://example.com/1/messaging/outbound/
tel%3A%2B12345678/subscriptions HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: example.com:80

{"deliveryReceiptSubscription": {
    "callbackReference": {
        "callbackData": " doSomething()",
        "notifyURL": "http://www.yoururl.here"
    }
}}
Use POST to create the message subscription. The senderAddress in the URL must be URL-escaped.Mandatory parameters:
notifyURL (URL) This will be used by the server to POST the notifications to you, so include the URL of your own listener application.

Optional parameters:
clientCorrelator (string) uniquely identifies this create subscription request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid creating a duplicate subscription.
callbackData (string) is a function name or other data that you would like included when the POST is received.

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/messaging/
outbound/subscriptions/sub789
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"deliveryReceiptSubscription": {
    "callbackReference": {
        "callbackData": "doSomething()",
        "notifyURL": " www.yourURL.here "
    },
    "resourceURL":
"http://example.com/1/messaging/outbound/subscriptions/sub789"}}
201 indicates the subscription has been created at the URI in the Location header. ‘sub789’ indicates the subscriptionID.The JSON response body simply confirms the creation of the subscription and the URL it will POST notifications to.

The format of the delivery receipt notification sent to your notifyURL is:

{"deliveryInfoList": {
    "deliveryInfo": [
        {  "address": "tel:1350000001",
           "deliveryStatus": "DeliveredToTerminal"},
        {   "address": "tel:1350000999",
            "deliveryStatus": "DeliveredToTerminal"}
    ],
    "link": {
        "href":
"http://example.com/exampleAPI/1/messaging/outbound/
tel%3A%2B1-555-0100/requests/{requestId)",
        "rel": "OutboundMessageRequest"
    },
    "resourceURL":
"http://example.com/exampleAPI/1/messaging/outbound/
tel%3A%2B1-555-0100/requests/req123/DeliveryInfos"
 }}

The deliveryInfo array in the deliveryInfoNotification contains address and deliveryStatus pairs for each user you have sent the MMS to.
The deliveryStatus can take the values shown above in the ‘Query delivery status of an MMS’ example, except for ‘MessageWaiting’, since that is the initial status. The callbackData will also be passed back to you, echoing what you provided when you created a message to send (‘Send an MMS from your Web application’) or subscribed to delivery notifications.
The link refers to the message URL (that was returned when the message was originally created).
The resourceURL simply refers to the URL of this request.

Stop the subscription to delivery notifications

DELETE http://example.com/1/messaging/
outbound/subscriptions/sub789 HTTP/1.1
Accept: application/json
Host: example.com:80

Make sure to use the correct subscriptionID in the URL.

Response:

HTTP/1.1 204 No Content
Date: Thu, 04 Jun 2009 02:51:59 GMT

204 confirms the subscription has been cancelled

Examples : Receiving Messages

Retrieve a list of messages sent to your Web application

GET http://example.com/1/messaging/
inbound/registrations/3456/messages?maxBatchSize=2  HTTP/1.1
Host: example.com:80
Accept: application/json

‘3456’ is the registrationIDagreed with the OneAPI operator.Optional parameters
maxBatchSize is the maximum number of messages to retrieve in this request

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"inboundMessageList": {
    "inboundMessage": [
        {   "dateTime": "2010-11-19T12:00:00",
            "destinationAddress": "6789",
            "inboundMMSMessage": {"subject": "Rock Festival 2010"},
            "messageId": "msg1",
            "resourceURL":
"http://example.com/1/messaging/inbound/
registrations/3456/messages/msg1",
            "senderAddress": "tel:+1234567" },
        {   "dateTime": "2010-11-19T12:15:00",
            "destinationAddress": "6789",
            "inboundMMSMessage": {"subject": "London Marathon"},
            "messageId": "msg2”,
            "resourceURL":
"http://example.com/1/messaging/inbound/
registrations/sub789/messages/msg2",
            "senderAddress": "tel:+7891234"
        }
    ],
    "numberOfMessagesInThisBatch": "2",
    "resourceURL":
"http://example.com/1/messaging/inbound/
registrations/3456/messages?maxBatchSize=2 ",
    "totalNumberOfPendingMessages": "20"
}}

The inboundMessageList object contains an inboundMessagearray with pairs detailing:

  • the dateTime that the message was received,
  • destinationAddress is the number associated with your service (for example an agreed short code, see ‘What do I need?’ above)
  • messageId is a server-generated message identifier
  • The inboundMMSMessage object contains a pair showing the subject of the message, which may determine whether you want to retrieve the entire MMS.
  • resourceURL is a link to the message. Use these to retrieve the entire message including attachments (see below).
  • senderAddress is the MSISDN or Anonymous Customer Reference of the sender.

The remainder of the inboundMMSMessageList object are pairs indicating the numberOfMessagesInThisBatch, a self-referring resourceURL, and the totalNumberOfPendingMessages awaiting retrieval from gateway storage.

Retrieve the full MMS including attachments

GET http://example.com/1/messaging/inbound/
registrations/3456/messages/msg1?resFormat=JSON HTTP/1.1
Host: example.com:80

Mandatory URI components
‘3456’ is the registrationID agreed with the OneAPI operator.
resFormat=JSON ensures a JSON response content-type.

Response:

HTTP/1.1 200 OK
Content-Type: multipart/form-data; boundary=”=====12345====”
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT

====12345====
Content-Disposition=multipart/form-data; name=”root-fields”
Content-Type=application/json
Content-Length: nnnn
{"inboundMessage": {
    "dateTime": "2010-11-19T12:00:00",
    "destinationAddress": "6789",
    "messageId": "msg1",
    "inboundMMSMessage": {"subject": Rock Festival 2010"},
    "resourceURL":
"http://example.com/1/messaging/inbound/
registrations/3456/messages/msg1",
    "senderAddress": " tel:+1234567"
}}

====12345====

Content-Disposition: form-data; name=”attachments”
Content-Type: multipart/mixed; boundary=”====aaabbb”
====aaabbb
Content-Disposition:attachments;filename=”textBody.txt”;
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8 bit

Look at the attached picture
====aaabbb
Content-Disposition:attachments;filename=”image1.gif”;
Content-Type: image/gif
MIME-Version: 1.0
Content-ID: 

GIF89a...binary image data...
====12345====
As this is a mulipart/form-data response, the message text and metadata (in JSON) are separated from the attachments by the boundary – in this case the string ”=====12345====”
Below the boundary are more header fields to describe the message format, as per ‘Encoding and Serialisation Details for MIME format’ above.An inboundMessage object is returned with pairs detailing:

  • the dateTime that the message was received,
  • destinationAddress is the number associated with your service (for example an agreed short code, see ‘What do I need?’ above)
  • messageId is a server-generated message identifier
  • The inboundMMSMessage object contains a pair showing the subject and message part of the message
  • resourceURL is a link to the message. Use these to retrieve the entire message including attachments (see below).
  • senderAddress is the MSISDN or Anonymous Customer Reference of the sender.
  • …and a self-referring resourceURL

The attachments follow the second boundary. If there is more than one attachment, a header block is included to denote that:
Content-Disposition: form-data; name=”attachments”
Content-Type: multipart/mixed; boundary=”====aaabbb”

…and then the boundary is used to separate each attachment. Note if there is only one attachment then this header block is not included.

Each attachment then has headers for
Content-Disposition
Content-Type with charset

Other headers are included depending on the Content-Type to assist in pasrsing.

Subscribe to notifications of messages sent to your application

POST http://example.com/1/messaging/
inbound/subscriptions HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json

destinationAddress=3456&
notifyURL=http://www.yoururl.here/notifications/
DeliveryInfoNotification&
criteria=Vote&
notificationFormat=JSON&
callbackData=doSomething()&
clientCorrelator=12345
Mandatory parameters
destinationAddress is the MSISDN, or code agreed with the operator, to which people may send an MMS to your application
notifyURL(URL) is your address to which notifications will be sentOptional parameters
criteria (string) is case-insensitve text to match against the first word of the message, ignoring any leading whitespace. This allows you to reuse a short code among various applications, each of which can register their own subscription with different criteria.
notificationFormat is the content type that notifications will be sent in – for OneAPI v1.0 only JSON is supported.
clientCorrelator (string) uniquely identifies this create subscription request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid creating a duplicate subscription.
callbackData (string) is a function name or other data that you would like included when the POST is received.

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://{serverRoot}/{apiVersion}/messaging/
inbound/subscriptions/{subscriptionId1}
Content-Length: 254
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"resourceReference": {"resourceURL":
"http://example.com/1/messaging/inbound/subscriptions/sub123”}}

201 indicates the subscription has been createdThe response body returns a resourceReference object containing a resourceURL pair indicating the URI of the newly created subscription.

The format of the message receipt notification sent to your notifyURL is:

POST {notify URL} HTTP/1.1
Accept: application/json
Content-Length: nnnn
Host: application.example.com:80
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"inboundMessageNotification":
{"inboundMessage": {
    "destinationAddress": "tel:+1-555-0100",
    "messageId": "msg123",
    "inboundMMSMessage": {"subject":
"Who is RESTing on the beach?"},
    "link": {
        "href":
"http://example.com/exampleAPI/1/messaging/
inbound/subscriptions/sub123",
        "rel": "Subscription"
    },
    "resourceURL": "http://example.com/exampleAPI/1/
messaging/inbound/registrations/reg123/messages/msg123",
    "senderAddress": "tel:+1-555-0101"
}}}
This will be sent for every MMS received (matching the optional criteria if provided). The HTTP Date header indicates the time of message arrival. The inboundMessageNotification object includes any callbackData for your own use, and an an inboundMessageobject containing:

  • The subject within the inboundMMSMessage part so that the application can decide whether to download the full MMS message
  • destinationAddress is the number associated with your service (for example an agreed short code, see ‘What do I need?’ above)
  • messageId is a server-generated message identifier
  • link is the URL of the subscription that received this message
  • resourceURL is a link to the message which can then be retrieved in full
  • senderAddress is the MSISDN or Anonymous Customer Reference of the sender.

Stop the subscription to message notifications

 DELETE http://example.com/1/messaging/
inbound/subscriptions/sub123 HTTP/1.1
Host: example.com:80

Make sure to use the correct subscriptionID in the URL.

Response:

HTTP/1.1 204 No content
Date: Thu, 04 Jun 2009 02:51:59 GMT

204 indicates the subscription has been deleted

Response codes and exceptions

HTTP response codes are used to indicate:
200 – Success!
400 – Bad request; check the error message and correct the request syntax.
401 – Authentication failure, check your OneAPI provider’s authentication requirements.
403 – Forbidden; please provide authentication credentials.
404 – Not found: mistake in the host or path of the service URI.
405 – Method not supported: in OneAPI Location v1 only GET is supported.
503 – Server busy and service unavailable. Please retry the request.

More details on these at http://www.ietf.org/rfc/rfc2616.txt

Exceptions:

{"requestError": {
    "policyException": {
        "messageId": "POL0001",
        "text": "A policy error occurred. Error code is
maxBatchSize exceeded. The maximum allowed maxBatchSize is %1.",
        "variables": "20"  }
}}

400 indicates an error
The requestError object contains either a serviceException or a policyException object.
A serviceException describes the reason why the service cannot accept the request; for example if the registrationId was incorrect.
A policyException object means that the request syntax is valid, however an operator policy has been broken: in this example because the operator cannot support the batch size requested.
serviceException and policyException share the same body: an identifier pair for the exception (messageId), a text pair to describe it consistently (text), and a variables pair to indicate any specific cause of the error (variables). The variables relate to the %1 placeholder(s) in the text.

List of service exceptions for MMS:

Id Exception Text Variables
SCV0283 Delivery receipt notification not supported none

… also see the Common Service Exceptions that apply to all OneAPI APIs.

List of policy exceptions for MMS:

There are no policy exceptions unique to SMS, but plus see the Common Policy Exceptions that apply to all OneAPI APIs.

Reference Material

OneAPI is a profile (subset) of Parlay REST v1.0. The full specifications and guidelines may be found at: http://www.openmobilealliance.org/Technical/current_releases.aspx

Changelog

May 23rd 2012 – corrected send MMS URI

Back
Contact GSMA Legal Email Preference Centre Copyright © 2014 GSMA. GSM and the GSM Logo are registered and owned by the GSMA.