Bulletin API Developer Guide

Skip to end of metadata
Go to start of metadata


Back to Knowledge Base

SIGN UP NOW

Table of Contents

Introduction..

This Bulletin API Developer Guide provides information on the simple REST based API for application developers and software integrators.

Before using the Bulletin API you must be subscribed to the Bulletin Messenger service - this is automatic for online signups.

Be sure to view the terms of service and feel free to contact us if you have any questions.

SIGN UP NOW

 

HTTP API

The Bulletin API provides the simplicity that you are looking for when enabling your applications to send SMS messages. Sending a message is as easy as POSTing a web form.
The HTTP API interface is contains the following methods:

  • Send a single message.
  • Obtain the status of messages you've sent (e.g. Learn when a message is received)
  • Receive replies to your message.

To use the API simply POST method parameters to the Bulletin Messenger server in the same way that a browser would.

To do this method parameters are first HTML form encoded and then submitted in a HTTP POST. This is well supported in most development environments.

Note: The number and order of parameters may vary. The parameter names described in this document will not change, however new parameters may be added from time to time.

 

Top Tips - useful pointers

Using a REST API is straightforward - no mucking around with XML and a very simple interface.

It is best to get familiar with the REST API outside of your code first - so that you can get a feel of how it hangs together without writing stuff and realising there may have been an oversight.

Chrome Users

Chrome has an awesome plugin called "Advanced Rest Client" inside the Chrome Store. With this app you can easily construct the API calls to Messenger - including saving them for later reference.

Unix/Linux Users

cURL is an awesome old-school tool for fetching and putting to web URL's from the command line. There is even a windows version if you don't fancy using Chrome as mentioned above. Because cURL is a command line tool you can build it into scripts such as Bash shell scripts and use those to interact with the Bulletin API. Perfect if you don't want to start involving developers.
 

Sending via an API

API URL

Action

HTTP Method

URL to Use

Sending Messages

POST

https://www.bulletinmessenger.net/api/3/sms/out

Sending Messages

Use secure HTTPS POST to send messages to https://www.bulletinmessenger.net/api/3/sms/out.
Recognised URL encoded parameters for sending messages are:

Name (case sensitive)

Description

Required?

Min. Version

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

/api/1

password

Your account password

YES

/api/1

to

Destination Number (MSISDN or Address book item (contact or group). For numbers, include the country code but do not include leading zeros, spaces, brackets or other formatting characters. You can send a message to multiple recipients by space-delimiting items.
Version 3 (/api/3) supports multiple recipients using a space-delimited list

YES

/api/1

body

The Message to send. Messages can be up to 480 characters long, although this can be controlled by fragmentationLimit. The allowable character set may vary depending on the destination network. In general characters from the GSM default character set are safe (see GSM 03.38). Set contentType to "text/plain; charset=UTF-16" to support richer alphabets.

YES

/api/1

from

Your Message Source MSISDN that you wish to use so that recipients can identify you. Only numbers or source strings that you have registered against your account can be used.
If undefined then the default value will be used from your account settings.

NO

/api/3

messageId

An identifier that you can use to track message status information for retrying due to errors or delays. Maximum 36 characters.
If undefined a UUID will be generated for you. Not valid with Virtual Numbers or Customer-Allocated Short Codes

NO

/api/3

fragmentationLimit

Sets maximum number of SMS message parts to use for Multipart SMS Messages. Gateways may not respect this setting, which may result in longer messages being delivered without warning.
If undefined this defaults to the "Long Messages" setting configured for your user

NO.

/api/3

contentType

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

NO

/api/3

callbackUrl

Provide a mailto, http, or https URL to be called when replies are made to this message. See Callback URLs 

NO

/api/3

callbackStatusUrl

Provide an http or https URL to be called when the status of this message changes. See Callback URLs

NO

/api/3

Example URL String

https://www.bulletinmessenger.net/api/3/sms/out?userId=yourId&password=yourPassword&to=64222222221&body=hello
Don't forget to use your password and an international-format number for the recipient, in the "to" parameter.

Bulletin Messenger will respond to each and every HTTP request with one of the following result codes, and an XML response in the HTTP body.

Code

Meaning

Action Required

200

Success!

Message Passed API validation, check the HTTP response XML for details if message subsequently fails

Note Bulletin Messenger versions earlier than /api/3 returned a 204 response, so be careful if you are upgrading

204

Success!

No action required. Valid for /api/1 only

400

Bad Request

Examine status line for error message

401

Unauthorized

Check you are using the correct URL as well as userId and password values

403

Forbidden

Check company limits and address book restrictions and that the recipient is either a) a number, or b) a contact or group.

Note Prepay users are limited to 100 messages per day and will get a 403 error if you exceed that. Contact Bulletin if you need this limit removed

500

Internal Error

Contact Bulletin

Important

It is important to note that the API may return a 200 Success result but still fail due to invalid contact name or possibly insufficient funds. You should get into the habit of checking the response XML for any issues in particular if sending to multiple recipients and/or members of your address book.

The following XML response example indicates a fundamental problem with the request which resulted in no messages being sent. In this case due to an authentication problem:

The following response indicates that processing was at least partially successful. The "salestem" error is likely due to a typo in the request, which should've been "salesteam".

Callback URLs

Messenger can call URLs you provide when certain events occur. These events are

  • The status of an outbound message has changed (e.g. it has been received). This is controlled by the callbackStatusUrl property.
  • An inbound message is received for your organisation. This is controlled by the callbackUrl property.

Note that default values can be defined for your organisation from within Messenger, and only need to be defined when using the API if they need to vary from the defaults.

Callback URL's can be up to 512 characters in length.

Each time an appropriate event occurs, Messenger will call your provided URL. Callback URLs can include variables that Messenger will populate dynamically at runtime.

Replies that trigger an HTTP or HTTPS callback process will retry for up to 48 hours if your service does not return a valid HTTP result code such as 200, 204, 301, 307.
Any codes in the 400+ range will result in retry. To avoid duplicate messages being posted to your service ensure you issue a HTTP 200 status code.

If the reply has NOT been successfully acknowledged within 48 hours it will be removed from the retry queue and can viewed on-line only.

The currently supported URL formats, which must be URL encoded prior to inclusion in the request, are httphttps, and, for callbackUrl only, mailto.

 ..

mailto protocol

The mailto protocol can be used for Email Notifications of replies made to your message. It supports two optional parameters:

Parameter Name

Purpose

Required

Subject

Controls the Subject used in the email notification

NO. If undefined will default to "RE:"

Body

Controls the Body of the email sent in the email notification

NO. If undefined will default to the body of the message sent by the recipient

Step 1: URL Encode your mailto parameters (if used)
Replace the newlines (\n below) with %0A and spaces with %20. Any other characters should also be encoded

Subject=Message: {!messageId}&Body={!body}\n\n-- \nIn Reply to {!messageId}\n\n

to get the encoded string below

Step 2: Concatenate the mailto string together as below

Step 3: Finally URL Encode the entire string, for use as the "callbackUrl" parameter

Note: This does result in 'double' encoding of the mailto parameters if used. This is correct and required.

Response format:

  • If the Body parameter has been defined, the body of the email delivered contains the evaluated value of the Body parameter, plus the original outbound message.
  • If the Body parameter has not been defined, the body of the email delivered contains the message sent by the recipient, plus the original outbound message.

e.g. Given the URL shown in the above example, if the original SMS was "Sign up for our competition", with a messageId of "FebPromo", and the recipient replied with "Yes Please", the email body delivered would be:

Yes Please


In Reply to FebPromo

>> Sign up for our competition

http and https protocol

These protocols are used to provide web-based notifications of message replies, and status updates. These protocols have no optional parameters and all properties and values are URL encoded when they are submitted to your web server.

Messenger will use the POST method to communicate with your service and expects a HTTP 200 status code result in return.

Example URL:

URL Encoded:

Status Callback format:

The http and https response sent to your callbackStatusUrl, called when a change is detected in the status of an outbound message, is available in two different formats. One is based on XML, and the other is an FORM POST format that is compatible with our other product, Bulletin Connect. The format used in the callback is defined by your Organisation on the Messenger website.

The XML document, contains the following properties:

Property

Purpose

messageId

Indicates the message that this reply is associated with. Either the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used.

to

A MSISDN or Short Code from Bulletin's threading range

from

The number of the handset that the status change is associated with. e.g. Who received the message.

statusCode

See Message Status Codes for simple descriptions of Codes used.

statusDate

The date the status message was received, formatted as ISO-8601 in the UTC Timezone

statusId

A unique identifier for this status message. Check this ID to ensure you have not already processed this status update.

error

More (readable) information about the Message Status, when available.

Example:

The FORM POST document contains the following properties:

Property

Purpose

messageId

A unique identifier for this status message. Check this ID to ensure you have not already processed this status update. Not valid with Virtual Numbers or Customer-Allocated Short Codes

to

A MSISDN or Short Code from Bulletin's threading range

from

The number of the handset that the status change is associated with. e.g. Who received the message.

statusCode

See Message Status Codes for simple descriptions of Codes used.

inReplyToId

Indicates the message that this reply is associated with. Either the messageId value returned in the /api/3/sms/out call, or "default" if /api/3/sms/out was not used.

error

More (readable) information about the Message Status, when available.

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

Message Callback format:

The http and https response sent to your callbackUrl, called when a message arrives for your Organisation, is available in two different formats. One is based on XML, and the other is an FORM POST format that is compatible with our other product, Bulletin Connect. The format used in the callback is defined by your Organisation on the Messenger website.

The XML document, contains the following properties:

Property

Purpose

messageId

For replies, this is the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Blank if this is not a reply. Not valid with Virtual Numbers or Customer-Allocated Short Codes

receivedDate

The date the reply message was received, formatted as ISO-8601 in the UTC Timezone

displayName

The human-readable version of the msisdn, if available

msisdn

The phone number that sent the message.

body

The content of the SMS message received from the MSISDN, formatted as CDATA.

Example:

The FORM POST document contains the following properties:

Property

Purpose

messageId

A unique identifier for this status message. Check this ID to ensure you have not already processed this status update. Not valid with Virtual Numbers or Customer-Allocated Short Codes

to

The number the message was sent to.

from

The number the message was sent from.

inReplyTold

Indicates the message that this reply is associated with. Either the messageId value returned in the /api/3/sms/out call, or "default" if /api/3/sms/out was not used. Blank if not a reply message.

body

URL encoded content of the users message

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

callbackUrl values for the HTTP and HTTPS protocols support these variables:

Name

Value

messageId

The value of the messageId parameter in the original request, or the system-generated UUID if messageId was undefined in your original message

body

The content of the SMS reply sent by the recipient in response to the original message.
We do not recommend including this at part of an http URL as it and the rest of the values are included in the XML document

recipient.msisdn

The recipient's MSISDN/phone number

recipient.displayname

The "display name" of the recipient, as used to send the original message

Receiving Messages

There are two ways to receive messages from the Bulletin API:

  1. You can either poll the server for incoming messages (pull method), or
  2. Have incoming messages sent (pushed) to your server as they are processed, using a callbackUrl

Polling is 'firewall friendly' and often easier to implement (especially if you are working outside an HTTP server).

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.

 

API URL

Action

HTTP Method

URL to Use

Receiving Message via Polling

POST

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

Required Input parameters are:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

The userId and password are supplied to you by Bulletin when you sign up for a Messenger account. You may pass them to the server in a query string, or in the HTTP Authorization header in Basic format.

Bulletin 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.

405

Incorrect Connection Method Used

Use the HTTP GET Method rather than POST.

500

Internal Error

Contact Bulletin

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

List Item

Description

Notes

messageId

A unique identifier for the message

Bulletin 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 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 as they are still considered MO messages.

body

Message Content

URL encoded content of the user's message

contentType

The content type used in the message

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

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

Example GET Request

Substitute your correct Bulletin Credentials for this in this example and if you have any incoming messages queued on the Bulletin API 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 has been 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 the patented 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 http://bulletinmessenger.net web site to view your incoming messages or use the Message Feeds to access message logs using your code/application.

 

Receiving Message Receipt (status information)

Clients can GET incoming receipts (status updates) from https://www.bulletinmessenger.net/api/1/sms/status or provide a endpoint for Bulletin to push the receipts to via statusCallbackUrl.

Required Input parameters are:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

The userId and password are supplied to you by Bulletin when you sign up for a Bulletin Messenger account.

The Bulletin API will respond to HTTP requests with one of the following result codes:

Code

Description

Notes

200

OK (normal result)

Parse the results for the incoming status details as described below then repoll to get another status.

204

No content (no messages)

No status messages waiting. Pause processing and retry after 30 seconds.

401

Unauthorized

Check userId and password.

405

Incorrect Connection Method Used

Use the HTTP GET Method rather than POST.

500

Internal Error

Contact Bulletin

For 200 codes (success) the Bulletin API will include a form encoded parameter list containing status information for a single message as described here:

List Item

Description

Notes

messageId

A unique identifier for the receipt

Bulletin API Unique ID. Check this ID to ensure you have not already processed this status update. Not valid with Virtual Numbers or Customer-Allocated Short Codes.

to

A MSISDN or Short Code from Bulletin's threading range

from

Destination MSISDN of message

The recipient's number of an outbound message sent by you (international format).

statusCode

Message status

See Message Status Codes for simple descriptions of Codes used.

inReplyToId

Correlation ID of the message

Matches the messageId sent by you in an outbound message.
If no messageId was set then this will contain default.

error

Descriptive text

More (readable) information about the Message Status.

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

 

Message Status Codes

Where ever supported Bulletin requests that carriers return delivery receipts so that these can be passed to you and processed. While every attempt is made to ensure that a valid statusCode is passed, it can not be guaranteed as some devices/carriers or connections are not able to provide a true delivery receipt.
Possible values of statusCode are:

Code

Basic Description

What this means to your Application

Final Status?

NUR

Number Unreachable

Check the number is correct and in International Format and then resend. The error string will also provide some more useful information such as whether the recipient is blocked. Be careful about infinite loops, only retry a couple of times.

Yes

SNT

Message Passed to Network

Wait. Give it a few minutes and then poll for more Status Messages.

No

ERR

Internal Error

An error occurred. It may be recoverable so try sending the message again in a few minutes. Be careful about infinite loops in your code.

Yes

NRCV or NRC

Not Received

Check the number is correct and in International Format and then resend. Be careful about infinite loops though.

Yes

RCV

Message Received

Excellent. This is a final status for this message and the handset has received it.

Yes

EXP

Message was not delivered within allowed time

This is a final status for this message and the handset has not received it. Retry if you want but for a lot of carriers this status may take days to return so the message may no longer be relevant.

Yes

INF

Insufficient funds

A billing error has occurred. If you get this error then your Bulletin Online account has reached its credit limit. This is very rare and you need to contact Bulletin immediately. No more messages can be sent until this is rectified.

Yes

top

Like Us on Facebook Follow Us On Twitter Share with Linkedin Watch on YouTube