Receive an SMS

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

Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.

Quick facts

Method

GET

Response required

HTTP 200 response with a non-empty body.

Prerequisites

Available for existing customers only.

More information

All information for this request is on this page.

Request from OpenMarket

An MO SMS request take the form of an HTTP GET request to your platform. You will need to provide us with a URL to your platform. To protect the data while in transit, we recommend using an HTTPS (SSL) URL.

Example request

https://yourplatform.example.com/drpt.cgi?smsfrom=447700900765&smsmsg=Hello+World&smsto=58870&smsid=4172212931&smsdate=2010-04-30+21%3A58%3A00

The possible parameters are in the table below. Note that:

  • If the message was in GSM03.38, you will receive the message via the smsmsg parameter in urlencoded Modified Latin-9, and will have the parameter bits=7.
  • If the message was in UCS-2, you will receive the message via the smsucs2 parameter in hexcode with the parameter bits=16. You will also have the smsmsg parameter in this case, with a "best guess" interpretation of the UCS-2 message.

Parameter

Description
smsfrom The mobile number (MSISDN) that the message originates from.
smsto The message originator— for example, your short code or VMN — that received the SMS message.
smsdate

The time and date that OpenMarket received the message, in the format:

yyyy-MM-dd hh:mm:ss.

This value is the current time and date in London, United Kingdom (either GMT or BST, depending on the time of year).
network

The mobile operator the end user is subscribed to. We can only determine this value for SMS messages sent to a short code.

For SMS messages sent to a VMN, we send the code UNKNOWN.
smsid A positive 64-bit integer used to uniquely identify the SMS message as it passes through the OpenMarket's systems. As well as when passing on a Mobile Originated SMS messages, OpenMarket will send SMS IDs with delivery reports and HTTP responses.
bits

Indicates the format of the SMS message body, as specified by the smsmsg parameter.

  • 7 - Modified Latin-9 character set.
  • 8 - hexadecimal encoded data. This is commonly used when the message body is binary code.
  • 16 - The message body is in UCS-2 Unicode, and both the smsmsg and smsucs2 parameter specify the message body. The smsmsg parameter value is a best-effort 7-bit text representation of the UCS-2 Unicode data carried in the smsucs2 parameter.

See Character sets and encodings for more information.
smsmsg The SMS message body. The format is indicated by the bits parameter.
smsudh

The UDH content sent with the SMS message. OpenMarket only sends this parameter when the SMS message contains UDH content.
smsucs2 This parameter is sent only when the message body is UCS-2 Unicode encoded messages. This parameter is hexadecimal encoded. Messages are commonly UCS-2 Unicode encoded when they contain special characters. The smsmsg parameter contains a best-effort text representation of this data.

Receiving concatenated messages

When receiving concatenated messages, the message will have a UDH (User Data Header) given in hexadecimal by the smsudh parameter in our GET request to your server; for example: smsudh=0500031C0302

The UDH for concatenated messages can be interpreted as follows as follows:

  • 05 - There are 5 bytes to follow
  • 00 - Indicator for concatenated message
  • 03 - There are 3 bytes to follow
  • 1C - Message Identifier — this is a random value that is the same for all parts of the message.
  • 03 - This is a three part message
  • 02 - Of which this is the second part

Responding to the request

You should respond with a non-empty HTTP 200 response. If a 200 response is not given within a timeout (60 seconds) then we retry the request. 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.