Bulletin Connect - Developer Guide

Skip to end of metadata
Go to start of metadata

 


Back to Knowledge Base

Bulletin SMPP

This Developer Guide provides information on the Bulletin Connect (now Bulletin SMPP) web service for application developers and software integrators.

Before using Bulletin SMPP you must be setup and allocated user credentials. Sign up online 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

Be Careful

The information and samples here are for the Bulletin SMPP API.
If you have signed up on-line please see the Bulletin API documentation or contact Bulletin to apply for a Bulletin SMPP Account.

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 SMPP. 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 SMPP 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 SMPP 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) 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.
top

HTTP Overview

The Bulletin SMPP 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 SMPP 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 SMPP Messaging REST URLs

top

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

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

Code

Meaning

Action Required

204

Success!

No action required
Note, if you use a browser to test your message syntax the browser will not show anything if you are successful. Only errors or warning will be displayed.

400

Bad Request

examine the HTTP header value for Status-Line for further error information

401

Unauthorized

Check you are using the correct URL as well as userId and password values

403

Forbidden

Check available funds, Check the rateCode you use is correct (case sensitive) and that you are not setting a sender number in the request

500

Internal Error

Retry your message after a pause of no less than 30 seconds and if it continues please Contact Bulletin

The userId and password are supplied to you by Bulletin when you sign up for a Bulletin SMPP 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 for setup details.
When using a rateCode to send a message ensure you use the actual rateCode that was provided by Bulletin (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. 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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

 

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

Code

Meaning

Action Required

200

You have scheduled messages

Parse the CSV contained in the Body
scheduledId,scheduled delivery time (unix timestamp),destinationMSISDN

00000000012345,1261088968,444122112112
00000000a32345,1261092968,444122115214

204

You have no scheduled messages

no action required

401

Unauthorized

Check you are using the correct URL as well as userId and password values

500

Internal Error

Retry your request after a pause of no less than 30 seconds and if it continues please Contact Bulletin

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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

ids

Space delimited list of scheduled message IDs returned from the #Listing Scheduled Messages request

YES

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

Code

Meaning

Action Required

200

Your scheduled messages have been deleted

Parse the urlencoded Body for the space delimited list of IDs that were deleted.

204

No scheduled messages were deleted

No action required.

401

Unauthorized

Check you are using the correct URL as well as userId and password values.

500

Internal Error

Retry your request after a pause of no less than 30 seconds and if it continues please Contact Bulletin

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 if you have any questions.

top

Example GET Request

Substitute your correct Bulletin Credentials for this in this example and if you have any incoming messages queued on Bulletin SMPP 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

Receiving Messages

There are two ways to receive messages from Bulletin SMPP:

  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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

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

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

Code

Meaning

Action Required

200

OK (normal result)

Parse the results for the incoming message details as described below.

204

No content (no messages)

No incoming messages. Pause processing and retry after 30 seconds.

401

Unauthorized

Check userId and password.

405

Incorrect Connection Method Used

Use the HTTP GET Method rather than POST.

500

Internal Error

Contact Bulletin

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

List Item

Description

Notes

messageId

A unique identifier for the message

Bulletin Connect Unique ID. Check this ID to ensure you have not already processed this incoming message (50 character (max) string).

from

Source MSISDN

The sender of the SMS message in International format.

to

Destination MSISDN

The number the message was sent to. Applies to MO messages only, not to reply messages.

rateCode

The rate code for the short code the message was sent to (if applicable)

inReplyToId

Correlation ID (if the message is a reply)

Matches the messageId sent by you in an outbound message.
If no messageId was set when you submitted the original message then this will contain default.
If the message is sent to a dedicated short code then the inReplyToId parameter will not be available even if it is a reply to a message you have sent from that short code as they are still considered MO messages.

body

Message Content

URL encoded content of the users message

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

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.

top

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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

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

Bulletin SMPP will respond to HTTP requests with one of the following result codes:

Code

Description

Notes

200

OK (normal result)

Parse the results for the incoming status details as described below then repoll to get another status.

204

No content (no messages)

No status messages waiting. Pause processing and retry after 30 seconds.

401

Unauthorized

Check userId and password.

405

Incorrect Connection Method Used

Use the HTTP GET Method rather than POST.

500

Internal Error

Contact Bulletin

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

List Item

Description

Notes

messageId

A unique identifier for the receipt

Bulletin SMPP Unique ID. Check this ID to ensure you have not already processed this status update (50 character (max) string).

to

A MSISDN or Short Code from Bulletin's threading range

from

Destination MSISDN of message

The recipients number of an outbound message sent by you (international format).

statusCode

Message status

See #Message Status Codes for simple descriptions of Codes used.

inReplyToId

Correlation ID of the message

Matches the messageId sent by you in an outbound message.
If no messageId was set then this will contain default.

error

Descriptive text

More (readable) information about the Message Status.

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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

Bulletin SMPP will respond to HTTP requests with one of the following result codes:

Code

Description

Notes

200

OK (normal result)

Parse the results for the number of MO and DR.
For example:
inCount=0&statusCount=0 indicates there are no messages in either queue
inCount=6&statusCount=189 indicates there are 6 MO and 189 DR queued.

401

Unauthorized

Check userId and password.

500

Internal Error

Contact Bulletin

Message Status Codes

Where ever supported Bulletin requests that carriers return delivery receipts so that these can be passed to you and processed. While every attempt is made to ensure that a valid statusCode is passed, it can not be guaranteed as some devices/carriers or connections are not able to provide a true delivery receipt.
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 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 SMPP 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 SMPP 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:

Name (case sensitive)

Description

Required?

userId

User name for authentication

YES

password

Password for authentication

YES

to

The shortcode that is assigned to you that the handset will send the number to

YES

from

The sender of the SMS message (eg the fake handset) in International format

YES

body

URL Encoded content of the fake SMS

YES

Result codes are the same as when submitting a message.

top

top

SMPP Overview

The Bulletin 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 SMPP Details

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

Host

smsc3.bulletin.net

Port

10000

Threading Settings

TON

4

NPI

0

Using a Message ID

There are two methods for reply and status tracking using mTAG threading with SMPP.

  1. Set your unique message ID as the sender address in your message
    • source TON must be 4
    • message ID is a numeric up to 19 characters in length
  2. Record the message id that is returned in the SMPP submit response.

Any replies and delivery receipts will contain the message id for linking to the original MT message. They will also contain the ID provided as your sender address if set in the original MT message.

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

TON

7

NPI

0

Source Address

rateCodes provided by Bulletin

Customised headers - ALPHA

TON

5

NPI

0

Source Address

The ALPHA string that you want to appear on the handset. Bulletin will need to allow this feature on your account

Customised headers - phone number

TON

1

NPI

0

Source Address

The phone that you want to appear as the sender on the handset. Bulletin will need to allow this feature on your account

top

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

UTF-16 messages are commonly used for messages composed in languages such as Chinese, Indian, Russian.

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

SMS Parts

7 bit Length

16 bit Length

1

160

70

2

306

134

3

459

201

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.

top

WAP Service Indication

When using WAP Push messages you should be aware of their limitations.

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.

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

top