Bulletin Connect Developer Guide

Important Update - Anti-Spam Bulletin Connect has a new anti-spam process in place. Once a mobile has sent stop to your account, they will no longer be able to receive messages from you. To take advantage of this feature include "to STOP SMS, reply STOP" in your messages. If you have your own proven opt-out process in place please contact Bulletin Wireless with details and we are able to exclude your account from the process. For more information see the STOP Message Handling Process section in this document.

Contents

SDK |

Introduction

This Developer Guide provides information on the Bulletin Connect web service for application developers and software integrators.
Before using Bulletin Connect you must be setup and allocated user credentials. Complete the online application form and you will be contacted with your credentials.
While this document focuses on the simple REST like HTTP interface other options are also available if you are migrating from legacy SMPP or SOAP services.
Be sure to view the terms of service and feel free to contact us if you have any questions.

Connection Types

HTTP

A lightweight API HTTP provides the simplicity that you're looking for. Sending a message is as easy as POSTing a web form, and receiving is as easy as GETting a web page. This document focuses on this easy to use method.

HTTP is the recommended interface to develop against Bulletin Connect. For additional security after debugging you can simply change to HTTPS (see below).

HTTPS

HTTP over SSL provides the security with the simplicity of HTTP. During testing and trouble shooting we recommend HTTP for easier debugging. For your production services HTTPS is recommended.

HTTPS and HTTP can be used interchangably but HTTPS provides additional security.

SOAP

An industry standard, SOAP is supported in all modern development environments. Use SOAP to address the Bulletin Connect interface in an object oriented and strongly typed manner, reducing development time and errors.
If you require more information about using the SOAP interface for Bulletin Connect please contact us.

The SOAP interface has been deprecated and does not support the same feature set as the HTTP interface. It is recommended that where practical you use HTTP.

SMPP

The short message peer-to-peer protocol (SMPP) is a telecommunications industry protocol for exchanging SMS messages between Telcos's (carriers). It also allows third parties (e.g. Bulletin Wireless) to submit messages allowing us to provide carrier grade connectivity to you.
If you use a legacy SMPP system and would like to remove your reliance on one carrier and reduce your overheads then contact us and ask about our SMPP Connector.

HTTP Overview

The Bulletin Connect HTTP interface is composed of three methods

1. to send messages,
2. to receive messages,
3. to receive receipts.

To use the API simply post method parameters to the Bulletin Connect 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. Please consult the examples section for further information.

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 Connect Messaging URLs

Sending Messages

Use HTTP POST to send messages to http://service.bulletinconnect.net/api/1/sms/out.

Recognised URL encoded parameters for sending messages are:

NOTE: The Content-Type HTTP header should be application/x-www-form-urlencoded
NOTE: If sending a UTF-16 message the Content-Type HTTP header must be application/x-www-form-urlencoded; charset=UTF-8

See here for some sample HTML.

Bulletin Connect 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 Connect 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 (Mobile Station ISDN number), i.e. the phone number to send the message to, including the country code. Do not include leading zeros, spaces, brackets or other formatting characters. To send a message to multiple recipients list the numbers, separated by spaces, in the to parameter (then URLencode).
Do not POST multiple to parameters.

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). For UTF-16, messages can be up to 70 Unicode characters long which must be UTF-8 encoded (before URL Encoding). That is, for UTF-16 messages the body parameter must be UrlEncode(UTF8Encode(Unicode message)) this will be sent through as UTF-16 to the handset.

The messageId is a free form string used to correlate messages with replies and read receipts. Any printable ASCII character can be used in the string, and it can be up to 36 characters long. The messageId will be returned to your application with receipts and replies.

The rateCode parameter is optional. It can be used to specify the source number of a message. If you wish to specify a source number for your messages Contact Bulletin Wireless for setup details.
When using a rateCode to send a message ensure you use the actual rateCode that was provided by Bulletin Wireless (this will not generally be a number).

The contentType specifies the type of message to send. Supported message types include vCard, vCalendar, and WAP service indication (see Extended Messaging section for more information). If not specified it defaults to text/plain.

Receiving Messages

There are two ways to receive messages from Bulletin Connect.

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.

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

To Receive a Message

Clients can GET incoming messages from http://service.bulletinconnect.net/api/1/sms/in.

Required Input parameters are:

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

Bulletin Connect will respond to each and every HTTP request with one of the following result codes.

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

N.B. 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 Bulletin Connect then you will download one of them if you access the URL in a browser.

http://service.bulletinconnect.net/api/1/sms/in?userId=yourBulletinID&password=yourBulletinPassword

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 rateCode and to values included in the content.

body=Play+the+eagles+long+run&contentType=text%2Fplain&from=6149123456&messageId=000000000012dde9&rateCode=yourUniqueRateCode&to=4040

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.

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=66071687&messageId=000000000012de7d

This is the same message when you do not set the messageId you set in your original outbound message.

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=default&messageId=000000000012de7d

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.

To Receive a Message Receipt

Clients can GET incoming receipts (status updates) from http://service.bulletinconnect.net/api/1/sms/status or provide a endpoint for Bulletin to push the receipts to.

Required Input parameters are:

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

Bulletin Connect will respond to HTTP requests with one of the following result codes.

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

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

Message Status Codes

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 Wireless immediately. No more messages can be sent until this is rectified.	Yes

Handy Hint To ensure you know the current status or your SMS message, ensure that you set a unique messageId in your outbound message and correlate it with the receipts (inReplyToId field) as you process them.

Handy Hint - 2 For messages to multiple recipients (in a single POST) your messageId will be the same for each recipient. Therefore you should use a dual key of the messageId and the from fields to track individual replies and status updates.

Message Re-transmission

If message transmission fails for any reason Bulletin Connect will resend the message after a short delay (by default one minute). In rare circumstances this can lead to your application receiving duplicate messages.
The messageId of each incoming message and each status message is guaranteed to be unique, so your application can use it to detect re-transmitted messages and reject duplicates.

STOP Message Handling Process

Bulletin Connect will add any handset that sends a stop message to a blocked list. This automated process will then prevent that handset from receiving any more messages from the Bulletin Connect account concerned.

When a stop SMS request is processed, Bulletin Connect will also send an email to the contact address for the Bulletin Connect account and send a reply SMS to the handset telling them that they will no longer receive any messages from your SMS service.

Any further attempts to send to the blocked number will result in a NUR status with an appropriate error description.

Actions and Alternatives

• How to remove a number that was added in error?
  • If you believe that a SMS response was not a true opt-out request then ask the recipient to contact us by phone quoting your Bulletin Connect Account ID and we will remove them from the blocked list.
• What if I have my own opt-out process in place?
  • If you have a proven opt-out process in place, that we feel is suitable, then we are happy to remove you from this process. If we do that then you will still get an email when we detect a stop request but we will not send any confirmation SMS to the handset or block any future messages to that number.
• Can I see a list of numbers that have opted out of my messages?
  • Sorry, no. The recipient has asked that they no longer receive messages from you therefore we do not want to provide you a list of these numbers that you can then potentially use elsewhere. If you have a specific number that you want clarified then please contact us and we will see what we can do to assist.

To Have Messages POSTed to Your Server

Contact the Bulletin Wireless services team and tell them the details of the URL you would like messages to be sent to and when messages and receipts arrive they will be POSTed to your URL using the form parameters used in Reply processing.

N.B. Bulletin Connect will keep re-transmitting messages if your application returns any result code other than 200 (OK) or 204 (No Content), or if the post fails.

Extended Messaging

Bulletin Connect supports the following extended message types

1. Multipart SMS Messages
2. WAP Service Indication
3. vCard (electronic business card)
4. vCalendar (events and appointments)

Multipart SMS Messages

Single SMS messages can not be more than 160 (7 bit) characters or 70 (16 bit) unicode (UCS2) characters in length, which may restrict the content that can be sent to phones.

To work around this problem, a standard has been developed that allows multiple SMS messages to be concatenated on a phone and presented to the user as one (long) message. This is known as Segmentation and Reassembly or concatenated SMS. Please note, not all handsets or carriers support concatenated SMS.

Bulletin Connect uses the message sending parameter fragmentationLimit to set the maximum number of parts to use. If this parameter is set, you will not be able to exceed the character limits listed in the table below. For example, passing parameter name="fragmentationLimit" value="2" will restrict the number of characters to 306 (7 bit) or 134 (16 bit).

In order to maintain maximum compatibility with handsets, Bulletin Connect limits the number of parts in a concatenated SMS to 3. If the content exceeds your limit or exceeds the system limit Bulletin Connect will return a 400 error.

WAP Service Indication

Used to send any URL to an internet enabled phone, service indications are ideal for delivering content such as media (images, sound or video) and delivering basic web pages (XHTML or WML format) that can contain text and media in a richer format than available via SMS.
Service indications are sent the same way as plain SMS messages, but with a contentType of application/vnd.wap.sic. The URL is XML formated and URLencoded (as with all parameters used) and sent to Bulletin Connect in the body parameter of the message sending POST:

Set the href attribute to the full web address (URL) of your content and the body text of thetag to a description of the content.

Different handsets handle service indication messages differently but basically the recipient will receive a SMS alert that shows the description you set in your message. They can then open the page (URL) you set using their mobile browser.

See http://service.bulletinconnect.net/demo/indicator.html for a demonstration webpage that shows the HTTP interface for sending Service Indication messages. You can view the source for this page here.

vCard (electronic business card)

Used to send contact details to a handset, vCards are sometimes referred to as "business cards."
The vCard specification is maintained by the Internet Mail Consortium here: http://www.imc.org/pdi/. It is a simple text based format that looks something like this:

vCards are effectively plain messages with the vCard details URL encoded and with a contentType parameter of text/directory when sending the message POST .
Multiple vCards can be sent in a single POST but you will need to ensure you set the fragmentationLimit to a proper level for the message to be delivered.

N.B. Different handsets have different levels of support for the vCard "standard" so try your message on a variety of handsets to see if you need to make adjustments to the information you provide.

vCalendar (events and appointments)

vCalendar messages are used to send appointments and reminders to a phone.
The standard is similar to the vCard standard and is also maintained by the Internet Mail Consortium. It is a simple text based format that looks something like this:

vCalendar messages also need to be URL encoded and sent the same way as other Bulletin Connect messages, but with a contentType of text/calendar.
Multiple VEVENT appointments/events can be sent in a single vCalendar POST but you will need to ensure you set the fragmentationLimit to a proper level for the message to be delivered.

Hints and Tips

• Remember to URL encode all parameters, especially the body parameter which will often contain characters that aren't allowed in form encoding.
• When serving content with WAP push make sure that your web server presents the correct mime types for your content.
• Wrap content in WML pages for a better user experience.
• Multipart messages are charged per part.
• Read the FAQ
• Extended messaging to CDMA networks is not currently supported (we will add support in the future).

SDK |