Receiving Incoming Messages via Polling

You may obtain information about Messages and Statuses via our Polling API. Polling is 'firewall friendly' and often easier to implement (especially if you are working outside an HTTP server), but for the best experience we recommend Callbacks.

Use secure HTTPS GET or POST (recommended) to receive messages via

Simple API Example

Here’s a simple GET example:

Don’t forget to use your login and password

All messages appear in this api – including those that have been notified via callbacks. Each call to this API returns a single unread message and then marks it as read

There are just two URL encoded parameters for polling messages:

Name Description Required?


User name for authentication (same as used for logging into the website). User name and password may be passed as form encoded parameters, or in the HTTP Authorization header in Basic format.



Your account password


Messenger will respond to each and every HTTP request with one of the following result codes:

Code Meaning Action Required


OK (normal result)

Parse the results for the incoming message details as described below.


No content (no messages)

No incoming messages. Pause processing and retry after 30 seconds.



Check userId and password.


Internal Error

Contact Bulletin

Polling Delays

Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour

Polling will only transmit unread messages within the Messenger platform and mark them as read once transmitted. Remember this when testing.

For 200 codes (success) Messenger will include a form encoded parameter list containing some or all of message information as described below.

Note: The order of the parameters may change so use value/pair matching rather than location mapping.

List Item Description Notes


A unique identifier for the message

Messenger Unique ID. Check this ID to ensure you have not already processed this incoming message.



The sender of the SMS message in International format.


Destination MSISDN

The number the message was sent to. Applies to MO messages messages only, not to reply messages.


Correlation ID (if the message is a reply)

Matches the messageId returned to you in the response to /api/3/sms/out. If no messageId was set when you submitted the original message then this will contain 'default'. If the message is sent to a dedicated short code then the inReplyToId parameter will not be available even if it is a reply to a message you have sent from that short code (or virtual number) as they are still considered MO messages.


Message Content

URL encoded content of the user's message


The Date that the message is received

Formatted as ISO-8601 in the UTC Timezone, for example: 2017-05-16T01:23:04.417Z


The content type used in the message

text/plain, or text/plain; charset=UTF-16

Example GET Request

Substitute your correct Messenger Credentials in this example and if you have any unread incoming messages available then you will download one of them if you access the URL in a browser.

Example Mobile Initiated Message Content

This shows the content of the request when the messages is not a reply but is an 'MO messages' message (ie: initiated by the handset).

Note: the to value is included in the content while the inReplyToId is not included.


Example Content for Reply Messages

This shows the content of the request when the messages is a reply to one you sent previously.

Note: the inReplyToId which will map to the messageId you set in your original outbound message.


This is the same message when you do not set the messageId you set in your original outbound message.


Handy Hint

To take advantage of 2-way SMS message threading ensure that you set a unique messageId in your outbound message and match it with the inReplyToId in the incoming message. You can not receive specific messages/replies using the API. Access the web site to view your incoming messages or use the Message Feed to access your Inbox using your code/application.