Bulletin Messenger - Developer Guide

Skip to end of metadata
Go to start of metadata

Redirection Notice
This page should redirect to Bulletin API Developer Guide in about 3 seconds.


Back to Knowledge Base
Back to User Guide

SIGN UP NOW

About Bulletin API

Table of Contents

 

 

Signing Up to Messenger

This Bulletin API Developer Guide provides information on the simple REST based API for application developers and software integrators. Before using 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.

Before you start you will need:

  • a valid email address
  • nothing else

The email address is used to validate your account and can also be used to send SMS via email once you are in the system. There is not much point using a one time email address as you will never be able to send SMS from it will you?

Or, if you have assimilated with Google then you can login using your Google ID.
Before you start you will need:

  • a valid Google account
  • a bit of trust

Once you have these at hand visit https://www.bulletin.net/sign-freetrial/messenger to signup.

As a bonus we will even give you a few free messages so you can see how it all works before you part with some of your hard earned cash.

You will receive an email full of information so read it and have a look at the links so you can get the most out of Messenger.

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. 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 messagesusing the available feeds.

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.

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.

top

Sending via an API

API URL

Action

HTTP Method

URL to Use

Sending Messages

POST

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

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 international number for the recipient.

top

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

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 not defined 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. More details below

NO

/api/3

top

Bulletin API 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 that 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 us 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.

top

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

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:

top

Callback URLs

Bulletin API will call your provided URL each time a reply is received to a message that was sent with the callbackUrl property defined. 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 mailtohttp and https.

mailto protocol

The mailto protocol is used for Email Notifications, and 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. 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:

Response format:

The http and https response is a simple XML document, containing the following properties:

Property

Purpose

messageId

Indicates the message that this reply is associated with

receivedDate

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

displayName

The recipient's display name, if any

msisdn

The recipient's phone number

body

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

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

Example:

top

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.

top

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