Receive an SMS (v3)

OpenMarket sends SMS messages as HTTP POST requests. Note that:

• The request body is URL-encoded
• We deliver the message text as a binary message, so you must convert the message from its hex-encoded format into a usable string

We will retry the request if we don't receive a response from your platform, or we receive a non-200 response, for up to 72 hours.

Note: If you're new to OpenMarket, then integrate with either our SMPP Global SMS or HTTP Global SMS operations.
Customers currently integrated using v3 mayto use it, although we encourage customers to migrate to v4 in order to take advantage of new features.

Quick facts

Request from OpenMarket

The request from OpenMarket includes data in the header field and request body. There are no parameters included in the request URL.

Header fields

There are no custom OpenMarket headers included in the request.

Example header

POST /OpenMarket.asp HTTP/1.1
Host: www.mycompany.com:80
User-Agent: OpenMarket/4.0.0
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 464

Request body

The request body contains the message details. The XML is URL-encoded.

Single part message

The following shows the delivery request while still URL-enocoded.

xml=%3C%3Fxml+version%3D%221.0%22+%3F%3E%0A%3Crequest+version%3D%223.0%22+protocol%3D%22wmp%22+type%3D%22deliver%22%3E%3Caccount+id%3D%22123-456-789-11111%22%2F%3E%3Cdestination+ton%3D%223%22+address%3D%2212345%22%2F%3E%3Csource+carrier%3D%22383%22+ton%3D%220%22+address%3D%22%2B12065551212%22%2F%3E%3Coption+datacoding%3D%227bit%22+%2F%3E%3Cmessage+udhi%3D%22false%22+data%3D%2248656c6c6f20576f726c64%22%2F%3E%3Cticket+id%3D%2201153-0121G-1524H-176NA%22%2F%3E%3C%2Frequest%3E

The above example when decoded is as follows.

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="deliver">
   <account id="123-456-789-11111" />
   <destination ton="3" address="12345" />
   <source carrier="383" ton="0" address="+12065551212" />
   <option datacoding="7bit" />
   <message udhi="false" data="48656c6c6f20576f726c64" />
   <ticket id="01153-0121G-1524H-176NA" />
</request>

Single part with user data header (UDH)

Some mobile operators include a UDH if specified by the end user's phone configuration or when the end user tries to send an enhanced message. To handle these messages your application must strip the UDH.

In UDH, the first byte of the data indicates the amount of the data following it and is included in the header portion of the text message. For example, if the first byte is 0x05, then the total header is 6 bytes long (1 byte for length field plus the 5 bytes for the header portion). If your application is going to strip this data and ignore it, then you should ignore the first 6 bytes of data.

The data attribute is a hex-encoded binary string.

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="deliver">
   <account id="123-456-789-12345" />
   <source ton="0" address="+17345551212" />
   <destination ton="3" address="45123" />
   <option datacoding="8BIT" />
   <message udhi="true" data="05000300010148656c6c6f20576f726c64" />
   <ticket id="12004-0128L-1242U-28D21" />
</request>

Multipart message

If a user sends in an MO message that exceeds the maximum single message length allowed by the originating mobile operator, the message will be split and delivered in multiple MO segments.

You can determine if an MO is a segment of a long message.

• The message UDHI attribute is true. When this is the case, a user data header (UDH) is encoded at the beginning of the message data attribute.
• When you decode the UDH:
  • The message data attribute contains the hexadecimal encoded message. Two characters in the hexadecimal encoded message represent a byte. The first byte of the message defines the number of bytes remaining in the UDH. In the example below "05" is the first byte, indicating there are five bytes in the UDH following the first byte. The full UDH in the first MO example below follows:
  • 05 00 03 44 02 01
  • The second byte of the UDH defines the type of message described in the UDH. In the example below, the value is "00" meaning concatenation. Concatenation is another term to describe a long message split into multiple segments.
  • The third byte defines how many bytes remain in the UDH. In the example below, the value is "03".
  • The fourth byte contains the reference number. The value must be the same for all message segments comprising the long message.
  • The fifth byte defines the total number of concatenated message segments comprising the long message. In the example below, the value is "02": two segments.
  • The sixth byte defines the concatenated message segment number. The first MO example below is the first segment of the concatenated message; the last byte of the UDH is "01". The second MO example below is the second and final segment of the concatenated message; the last byte of the UDH is "02".

The first MO example, with the last byte of the UDH set to "01":

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="deliver">
   <account id="123-456-789-11111"/>
   <destination ton="3" address="22345"/>
   <source carrier="77" ton="0" address="+12061230053"/>
   <option datacoding="7bit" />
   <message udhi="true" data="0500034402013132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132"/>
   <ticket id="0114E-0602R-2013E-27489"/>
</request>

The second MO example, with the last byte of the UDH set to "02":

<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="deliver">
   <account id="123-456-789-11111"/>
   <destination ton="3" address="22345"/>
   <source carrier="77" ton="0" address="+12061230053"/>
   <option datacoding="7bit" />
   <message udhi="true" data="05000344020223334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334353637383930313233343536373839303132333435363738393031323334"/>
   <ticket id="0114E-0602R-2013F-27LQ0"/>
</request>

request element

account element

destination element

source element

message element

ticket element

option element

Responding to the request

Your platform should respond with an HTTP 200 response with "OK" in the response body. This response must be given in a timely manner (within 10 seconds).

HTTP/1.1 200 OK
Server: Microsoft IIS/6.0
Date: Tue, 29 Mar 2004 18:44:02 GMT
Content-Length: 2
Connection: close
Content-Type: text/html
					
OK

OpenMarket will retry the request if we don't receive a response from your platform, or we receive a non-200 response. We will retry the request for up to 72 hours. You will need to make sure that you filter duplicate requests.

Testing your integration

See Testing Your SMS v3 Integration.

Troubleshooting

I'm not receiving any SMS message requests

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.