Bulletin Connect Developer Guide

Important Update - Anti-Spam Bulletin Connect's anti-spam process in place by default. 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.net 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.net) 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. Your account will need to be enabled for this before you are able to access it.

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 REST 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

Name (case sensitive)	Description	Required?
userId	User name for authentication	YES
password	Password for authentication	YES
to	Destination MSISDN(s)	YES Use International Format
body	M essage Payload	YES
messageId	Client message identifier	Optional, (maximum 36 characters). Use this if you want to take advantage of Bulletin's patented mTAGTM technology or if you want to track message status information for retrying due to errors or delays.
rateCode	Message source MSISDN specifier	Optional. Contact Bulletin for Premium Billing/Routing options
from	Message source MSISDN, can not be used with rateCode	Optional. Contact Bulletin for this to be enabled on your account and for Premium Billing/Routing options
contentType	The type of message	Optional. Used for WAP Push Service Indication, vCard, vCal messages and UTF-16 SMS messages. For UTF-16 SMS messages, this must be set to text/plain; charset=UTF-16.
fragmentationLimit	Integer value between 0 and 3	Optional. Sets maximum number of SMS message parts to use for Multipart SMS Messages, default is 0 which indicates the current maximum (3) is used
routingHint	Indicates prefered route for message	Optional. Contact Bulletin for this to be enabled on your account and further information
schedule	Unix time for message delivery	Optional. Contact Bulletin for this feature to be enabled on your account

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.net 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.net for setup details.
When using a rateCode to send a message ensure you use the actual rateCode that was provided by Bulletin.net (this will not generally be a number).

If you require dynamic source numbers then your account will need to be enabled to use the from parameter. This is not recommended and additional costs may apply for this feature. See the Setting Source Numbers Using from Parameter section for details.

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.

If you want to schedule messages for future delivery please Contact Bulletin.net. If your account is not enabled for this feature you will receive an HTTP 400 error.
Bulletin Connect takes a Unix time parameter for scheduling messages and must fall within a date range than is no more than 13 months in the future. Messages scheduled for a time in the past 24 hours willl be sent immediately.
Any other value for the schedule parameter will cause a HTTP 400 error.
For various resources related to calculating Unix time, see http://www.epochconverter.com

Listing Scheduled Messages

Limited information is available about your scheduled messages using the http://service.bulletinconnect.net/api/1/sms/scheduled/list endpoint
Recognised URL encoded parameters for listing scheduled messages are:

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

00000000012345,1261088968,444122112112
00000000a32345,1261092968,444122115214

Deleting Scheduled Messages

You can delete your scheduled messages using the http://service.bulletinconnect.net/api/1/sms/scheduled/delete endpoint
Recognised URL encoded parameters for deleting scheduled messages are:

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

You scheduled message will not be deleted (eg a HTTP 204 result) if it has already been dispatched or deleted or if the ID does not exist

Setting Source Numbers using from Parameter

For clients allowed to use the from parameter when sending messages the following caveats apply to alphanumeric source headers to ensure delivery

1. a-zA-Z
2. 0-9
3. the source should have maximum of 11 characters
4. symbols are not allowed

You should be aware that when setting the source number that

1. replies are not available as they will not be routed back to your account.
2. you must ensure that any legal obligations with regards to unsolicited messages or opt-out regulations are complied with as users will not be able to opt out by reply SMS.
3. some networks and handsets do not support Alpha source numbers so your message may not be delivered as expected.

Please ensure that you cover all compliance requirements if you need to want this feature enabled. Contact Bulletin.net if you have any questions.

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.net 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 while the inReplyToId is not included.

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

Blocked Recipients The format of status receipts for blocked recipients is slightly different than that of other status messages. This inconsistency will be corrected in the next release of the API. IF you have any questions please contact us.

Queue Depth

Clients can GET a count of messages in their MO and DR (delivery receipts) queues from http://service.bulletinconnect.net/api/1/sms/queue.
Required Input parameters are:

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

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

Testing your MO handling

To fake an MO message to your Bulletin Connect account the API has a test endpoint at http://service.bulletinconnect.net/api/1/sms/test. This is used for MO messages only, not for faking replies.

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

Recognised URL encoded parameters for sending messages are:

NOTE: The Content-Type HTTP header should be application/x-www-form-urlencoded
NOTE: HTTP Basic auth is not supported at this time for the /test endpoint

Required Input parameters are:

Result codes are the same as when submitting a message.

SMPP Overview

The Bulletin Connect SMPP interface is based on version 3.4 of the SMPP specification.

See the API Interface Comparison Matrix for a side by side comparison of the different interfaces available.

Bulletin Connect SMPP Details

Your account will need to be configured to use SMPP before you can connect. Please contact Bulletin.net to enable this if required.

Threading Settings

Setting Source

Being able to set the source number (eg for premium billing) requires a rateCodes or your account settings changed to support customised headers. Contact Bulletin.net with specific use cases so we can assist with configuring your account.

Using a rateCode

This is the recommended way to set the source for a message.

Customised headers - ALHPA

Customised headers - phone number

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.net 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.
Bulletin may remove queued messages older than 7 days and stop pushing messages until you have indicated that your application is able to process them correctly.

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 |