Bulletin TXT Messenger Developer Guide

top

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 follow 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).

top

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

Example URL String https://www.bulletinmessenger.net/api/1/sms/out?userId=yourId&password=yourEncodedPassword&to=recipientNumber&body=hello Dont forget to use your encoded password and international number for the recipient.

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. Refer to this as the api-hash-password

Access to an Address Book via an API

HTTP API

A lightweight API provides the simplicity that you're looking for when wanting to get access your applications to address books. This API composed of FIVE methods:

1. get a list of address books.
2. get a content of a particular address book.
3. add new address book.
4. update an address book.
5. remove an address book.

Bulletin Messenger Address Book API URL

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

Address books list

Use secure HTTPS POST / GET to get access to https://www.bulletinmessenger.net/api/2/addressbook.
Recognised URL encoded parameters for getting an address book list 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

Example URL String https://www.bulletinmessenger.net/api/2/addressbook

Address book content

Use secure HTTPS POST / GET to get access to https://www.bulletinmessenger.net/api/2/addressbook.
Recognised URL encoded parameters for getting a content of an address book 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
id	An address book id. You can get using the following service call.	YES

Example URL String https://www.bulletinmessenger.net/api/2/addressbook?id=1234567

Add new address book

Use secure HTTPS POST / GET to get access to https://www.bulletinmessenger.net/api/2/addressbook.
Recognised URL encoded parameters for creating new address book 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
action	Supported value for this call is add.	YES
name	A name of new address book.	YES
type	An address book type.	NO
gid	An address book group id.	YES

Example URL String https://www.bulletinmessenger.net/api/2/addressbook?action=add&name=newName&type=newType&gid=1

Update address book

Use secure HTTPS POST / GET to get access to https://www.bulletinmessenger.net/api/2/addressbook.
Recognised URL encoded parameters for updating an address book 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
action	Supported value for this call is update.	YES
id	An address book id. You can get using the following service call.	YES
name	A new name of an address book.	YES

Example URL String https://www.bulletinmessenger.net/api/2/addressbookaction=update&id=1234567&name=newName

Remove an address book

Use secure HTTPS POST / GET to get access to https://www.bulletinmessenger.net/api/2/addressbook.
Recognised URL encoded parameters for removing an address book 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
action	Supported value for this call is remove.	YES
id	An address book id. You can get using the following service call.	YES

Example URL String https://www.bulletinmessenger.net/api/2/addressbook?action=remove&id=1234567

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.

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.