Receive an SMS

A mobile originated (MO) message request delivers an SMS message from one of your end users to your own systems.

To receive MO messages, you'll need a text-enabled number, such as a short code or VMN, provisioned with the mobile operators. You will also need to provide us with at least one URL to which we can send the messages. If you are using multiple URLs to receive MO messages, please also let us know what URLs you want us to send MO requests that use Basic authentication.

If our first attempt to deliver an MO message to your systems is not successful, we will retry the request for up to three days.

Quick facts

Content types

OpenMarket forwards the MO SMS message as:

• Plain text — When the content is UTF-8 and doesn't contain any unusual characters.
• Hexadecimal-encoded text — When it is a multipart message, the content contains control characters such as carriage returns, or there is a user data header (UDH).
• Binary data — When we have received a binary message from the mobile operator. You must convert the message from its hex-encoded format into a usable string.

Multipart messages

If you are sent a multipart message, we forward each part of the message separately. The request will use hexadecimal-encoded text and each part will include a UDH that is at the start of each part's content.

Depending on the mobile phone and mobile operator, the UDH for multipart messages can differ to use either a 1-octet or 2-octet message reference. There might also be other headers included with the message. However, by far the most common UDH we receive for multipart messages is the 1-octet version, without additional headers. This uses 6 bytes (two characters in the hexadecimal message format), similar to "05 00 03 44 02 01". When you decode the UDH:

• Byte 1: Defines the number of bytes in the UDH (excluding itself). In the example, this is "05", indicating there are five bytes in the UDH following the first byte.
• Byte 2: Defines the type of message you have been sent. "00" means it is a multipart message.
• Byte 3: Similar to byte 1. Defines how many bytes remain in the rest of the UDH. In the example, this is "03".
• Byte 4: Contains a reference number. The value will be the same for each part of the multipart message.
• Byte 5: Provides the number of parts used to send the multipart message. For example, "02" means the multipart message is made of two parts.
• Byte 6: Identifies the message part. The numbering begins at "01".

You can find out more about UDH sent with messages in the GSM specification.

Request from OpenMarket

Header fields

The request header from OpenMarket will look similar to the following:

POST / HTTP/1.1
User-Agent: OpenMarket
X-API-Version: 4
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Content-Length: 424
Connection: close

Custom fields

Request body

Example where the message is from a UK end user, and is sent as plain text:

{
   "mobileOriginate": {
      "submittedDate": "2015-08-29T15:10:03.029-05:00",
      "ticketId": "8514F-01278-17445-23FSJ",
      "source": {
         "ton": 1,
         "address": "447700900999"
      },
      "destination": {
         "ton": 3,
         "address": "58870"
      },
      "message": {
         "type": "text",
         "content": "I wish to register a complaint"
      }
   }
}

Example where the message is from a US end user, and is sent as hexadecimal-encoded text:

{
   "mobileOriginate": {
      "submittedDate": "2015-08-29T15:10:03.029-05:00",
      "ticketId": "8514F-01278-17445-23FSJ",
      "source": {
         "ton": 1,
         "address": "12515550145",
         "mobileOperatorId" : 383
      },
      "destination": {
         "ton": 3,
         "address": "222111"
      },
      "message": {
         "type": "hexEncodedText",
         "content": "050003080202207468696e6b696e672061626f75742069742e",
         "udh": true
      }
   }
}

JSON properties

The JSON body has a top-level object that contains the one member, mobileOriginate.

Multiples of the same object or member will not occur.

mobileOriginate object

YYYY-MM-DDTHH:MM:SSZ

2015-09-22T04:10:33Z

source object

Object that contains details about the message sender (the end user's details).

This object is always included in the request.

destination object

Object that contains details about the message recipient (your details).

This object is always included in the request.

message object

Object that contains details about the message you have received.

This object is always included in the request.

Responding to the request

When you receive an OpenMarket MO message request, return an HTTP 200 or 201 response with an empty response body. OpenMarket will retry the request if it does not receive a response from your platform, or receives a non-200 response. You will need to make sure that you filter duplicate requests.

If there are any errors receiving the request, please use standard HTTP error response codes.

Testing your integration

The Customer Integration Environment (CIE) does not simulate MO messaging. To test MO messages, you will need to use a text-enabled number that can currently receive messages. If you do not have a number provisioned, then you may use one of our demo numbers to test with. Contact your OpenMarket account manager to provision this.

Troubleshooting

I can't seem to receive MO messages over HTTPS

If you do not receive requests from us to an HTTPS URL, but you can receive them over standard HTTP, a possible cause is that we do not recognize and trust your server's security certificate. You must obtain an additional certificate from one of the trusted certification authorities.