Introduction

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.

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

Subscribing to Bulletin Messenger

The easiest way for new users to start using Bulletin Messenger is to this simple 4 step process.

1. Complete this form with a few pieces of information.
2. Enter the unique string
   • this is to prevent automated signups that use our free messages to SPAM, sorry for the inconvienience
3. 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.
4. If your reply is successful you will receive an SMS with your UserID and Password that can be used
   • to access the web site, or
   • to use in your own widget/tool or someone elses, or
   • use the Bulletin Messenger API

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.

1. 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.
2. 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.
3. 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.
4. 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

1. to send a single message

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 HTTP POST. 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.

Bulletin Messenger API URL

Sending Messages

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

Name (case sensitive)	Description	Required?
userId	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.

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.

You can copy and paste the correct hash from http://bulletinmessenger.net in your Messenger Settings.

To generate the SHA1 hash for the API you can use any appropriate library (eg the javascript one here) and follow these steps.

1. Generate an SHA1 hash of your account password
2. encode as base 64 (refer to this as password-hash)
3. Generate an SHA1 hash of account username + password-hash (no spaces),
4. encode as base 64 (refer to this as the api-hash)

Message Log Feeds

Using a secure HTTPS GET 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

Feed Parameters

Use HTTPS GET to retrieve messages from https://www.bulletinmessenger.net/api/2/sms/list.
Recognised URL encoded parameters for retrieving messages are:

Name (case sensitive)	Valid Values	Description	Required?
userId	String	User name for authentication	YES
password	String	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.	YES
format	atom rss	Default feed format is ATOM 1.0
type	out reply	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.