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 https://www.bulletinmessenger.net/api/1/sms/in

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?
userId	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.	YES
password	Your account password	YES

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

Code	Meaning	Action Required
200	OK (normal result)	Parse the results for the incoming message details as described below.
204	No content (no messages)	No incoming messages. Pause processing and retry after 30 seconds.
401	Unauthorized	Check userId and password.
500	Internal Error	Contact Bulletin

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
messageId	A unique identifier for the message	Messenger Unique ID. Check this ID to ensure you have not already processed this incoming message.
from	Source MSISDN	The sender of the SMS message in International format.
to	Destination MSISDN	The number the message was sent to. Applies to MO messages messages only, not to reply messages.
inReplyToId	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.
body	Message Content	URL encoded content of the user's message
messageDate	The Date that the message is received	Formatted as ISO-8601 in the UTC Timezone, for example: 2017-05-16T01:23:04.417Z
contentType	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.

https://www.bulletinmessenger.net/api/1/sms/in?userId=yourUserID&password=yourPassword

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.

body=Play+the+eagles+long+run&contentType=text%2Fplain&from=6149123456&messageId=3685355&to=4040&messageDate=2017-05-16T01%3A23%3A04.417Z

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.

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=66071687&messageId=3685355

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

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=default&messageId=3685355