HTTP Global SMS API

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

Method

POST with JSON 

Response required

HTTP 200 or 201 response with an empty response body.

Available

 

All regions.

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

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

Field

Description

X-API-Version

Identifies that this request comes from version 4 of our HTTP API.

Returned: Always

Type: A string of 1 to 30 characters in length.

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

Member

Description

submittedDate

The time and date that OpenMarket received the MO message from the mobile operator. The submitted date is expressed in ISO 8601 date and time format with an offset from UTC. The date string is in the following form::

YYYY-MM-DDTHH:MM:SSZ

Example:

2015-09-22T04:10:33Z

Returned: always

Type: string

ticketId

The ticket ID that identifies the SMS message in OpenMarket requests and reporting. The maximum length is 23 characters.

Returned: always

Type: string

source

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

Returned: always

destination

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

Returned: always

message

Object that contains details about the message you have received.

Returned: always

source object

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

This object is always included in the request.

Member

Description

address

The number from which the message was sent. For MOs this value will be an internationally formatted number; e.g. a mobile number that includes a country code, e.g.:

  • 447700900750 (UK mobile number)
  • 12515550100 (US mobile number)

The maximum length is 20 characters.

Returned: always

Type: string

ton

Indicates what type of number is set in address. This will always be 1 which indicates that it is an international format number.

Returned: always

Type: integer

mobileOperatorId

Identifies the mobile operator that provides services to the number. This is an OpenMarket-specific number.

For a list of the valid IDs, see Mobile Operator IDs.

Returned: not always returned

Type: integer

destination object

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

This object is always included in the request.

Member

Description

address

The number to which the end user sent the message. For MOs this value will be either:

  • An internationally formatted number; e.g. your toll-free, landline, VMN, or long code.
  • A short code.

The maximum length is 20 characters.

Returned: always

Type: string

ton

Indicates what type of number is set in address. Either:

  • 1 — An international format number
  • 3 — A short code

Returned: always

Type: integer

message object

Object that contains details about the message you have received.

This object is always included in the request.

Member

Description

type

Identifies what type of message you have received (text or binary). For text messages, it also identifies whether the text is hex-encoded. Options are:

  • text — Message is in UTF-8.
  • hexEncodedText — Message is hex-encoded, UTF-8.
  • binary — Message is binary content.

Returned: always

Type: string

content

The message sent to you. This is an alphanumeric string from 0 to 2680 characters long.

Returned: always

Type: string

udh

Indicates whether a user data header (UDH) is encoded in the message. Either:

  • true — There is a UDH
  • false — There is no UDH

Returned: only when the type is either hexEncodedText or binary.Otherwise, this is optional.

Default: false

Type: boolean

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.