This Bulletin Messenger Developer Guide provides information on the simple REST based API for application developers and software integrators.
Before using Bulletin Messenger you must be setup in Bulletin Online and subscribed to the Bulletin Messenger service.
The easiest way for new users to start using Bulletin Messenger is to this simple 4 step process.
Complete this form with a few pieces of information.
Enter the unique string
this is to prevent automated signups that use our free messages to SPAM, sorry for the inconvienience
Reply to the SMS that will be sent to your phone with the word confirm.
Note, your mobile number can only be used once for our services. If you make a mistake or need an additional account then please contact us and we will try to assist.
If your reply is successful you will receive an SMS with your UserID and Password that can be used
Once subscribed you can take advantage of the free messages offered for a limited time. When the offer expires, or you use all your free messages, you can simply top up your account using the secure payment systems such as PayPal or Payment Express (NZ only).
Sending via an API
HTTP API
A lightweight API provides the simplicity that you're looking for when wanting to enable your applications to send SMS messages. Sending a message is as easy as POSTing a web form.
The following limits are in place for this API.
Only one recipient per connection. If you need to send to multiple recipients then you will need to loop through your recipient list sending to one each time.
Message Status is not reported back via the API. The status will be updated and can be viewed by logging in to Bulletin Messenger or by requesting a list of recent messages using the available feeds.
Replies are not handled by the API. Replies can be viewed by logging in to Bulletin Messenger or by requesting a list of recent messages using the available feeds.
Message length is ignored by the API and messages are not split into parts.
If your needs exceed these limits then consider using Bulletin Connect which offers a carrier grade API using a setup that is very similar to that described here but without the restrictions.
See the Feature Comparison Matrix for information on what features are available in each of the Bulletin messaging API's.
HTTP Overview
The HTTP API interface is composed of ONE method only
To use the API simply post method parameters to the Bulletin Messenger server in the same way that a browser would submit a form.
To do this method parameters are first HTML form encoded and then submitted in an HTTPPOST. This is simple and well supported in almost all development environments.
N.B. The number and order of parameters may vary. While the parameter names described in this document will not change, additional parameters may be added to the API from time to time.
User name for authentication (same as used for logging into the website)
YES
password
A SHA1 hash of your account and password details. Failure to provide this will result in an Authentication error even if you provide the password.
See the SHA1 Password Hash section for more information on generating the hash or login to http://bulletinmessenger.net and view your Messenger Settings for the correct string to use.
YES
to
Destination Number or Addressbook item (contact or group)
YES, one item only
body
Message Payload
YES
Bulletin Messenger will respond to each and every HTTP request with one of the following result codes.
Code
Meaning
Action Required
204
Success!
No action required
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 addressbook restrictions and that the recipient is either a) a number, or b) a contact or group.
The userId and password are supplied to you by Bulletin Wireless when you sign up for a Bulletin Messenger account. You may pass them to the server as form encoded parameters, or in the HTTP Authorization header in Basic format.
The to parameter is the destination Number (MSISDN or Addressbook item such as a Contact or Group. For numbers, include the country code but do not include leading zeros, spaces, brackets or other formatting characters. To send a message to multiple recipients POST multiple times or configure groups in your online Addressbooks.
The body parameter is used to pass the message. Messages can be up to 160 characters long. 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). If you send longer messages they will be logged as POSTed but only the first 160 characters will be sent. Note, this may change at anytime and result in longer messages being delivered without warning.
Receiving Messages
You can not receive individual 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)
You can not receive individual message receipts using the API. Access the http://bulletinmessenger.net web site to view the status of your messages or use the the Message Feeds to access message logs (including status information) using your code/application.
SHA1 Password Hash
The Bulletin Messenger API requires a SHA1 hash of the password. Failure to provide this will result in an 401 authentication error even if you provide the correct password.
To generate the SHA1 hash for the API you can use any appropriate library (eg the javascript one here) and follow these steps.
Generate an SHA1 hash of your account password
encode as base 64 (refer to this as password-hash)
Generate an SHA1 hash of account username + password-hash (no spaces),
encode as base 64 (refer to this as the api-hash)
Message Log Feeds
Using a secure HTTPSGET interface, Bulletin Messenger offers access to the online Message Log to allow you to request a list of your recent messages that can be used in your application or software.
The details provided here are targeted at the application developer and it is assumes a knowledge of RSS and the HTTP web services.
Message Feed Details
Feed URL
Recent messages can be retreived from the following URL
A SHA1 hash of your account and password details. Failure to provide this will result in an Authentication error even if you provide the password.
See here for more information on generating the hash or login to http://bulletinmessenger.net and view your Messenger Settings for the correct string to use.
The type of messages to return, default type is to return both out and reply
Your application will parse the resulting XML feed and display or manipulate your recent messages.
The maximum number of messages returned is controled by your online display options in Bulletin Messenger.
Details of your account including account balance, type and currency is included in the feed results. This will allow you to monitor your account status and initiate a payment before your service is restricted.
Feed Examples
ATOM Example Results
If your HTTPS request has the format=atom parameter, or if the format parameter is omitted then the results will be in ATOM format ().
RSS Example Results
If your HTTPS request has the format=rss parameter then the results will be in RSS format ().
Examples
For some examples of widgets/tools/applications and things that make use of the Bulletin Messenger API see here.