API Introduction
The Messenger API provides the simplicity that you are looking for when enabling your applications to send SMS messages. Sending a message is as easy as POSTing a web form.
The HTTP API interface contains the following functions:
| API | Purpose | Documentation |
|---|---|---|
https://www.bulletinmessenger.net/api/3/sms/out | Send a single message | here |
https://www.bulletinmessenger.net/api/1/sms/in | Receive a single incoming message via polling | here |
https://www.bulletinmessenger.net/api/3/sms/out/poll | Receive a outgoing messages via polling | here |
https://www.bulletinmessenger.net/api/1/sms/status | Receive the status of messages you've sent (e.g. Learn when a message is received) via polling | here |
https://www.bulletinmessenger.net/api/2/sms/list | Receive a list of recent messages via polling | here |
| n/a | Receive incoming messages and statuses via http callback | here |
To use the API simply authenticate your user and POST method parameters to the Messenger server in the same way that a browser would.
To do this method parameters are first HTML form encoded and then submitted in a HTTP POST. This is well supported in most development environments.
Note: The number and order of parameters may vary. The parameter names described in this document will not change, however new parameters may be added from time to time.
Top Tips - useful pointers
Using a REST API is straightforward - no mucking around with XML and a very simple interface.
It is best to get familiar with the REST API outside of your code first - so that you can get a feel of how it hangs together without writing stuff and realising there may have been an oversight.
GUI Tools
We can recommend Postman as a way to easily construct the API calls to Messenger - including saving them for later reference.
Command line tools
cURL is an awesome old-school tool for fetching and putting to web URL's from the command line. There is even a Windows version if you don't fancy using a GUI as mentioned above. Because cURL is a command line tool you can build it into scripts such as Bash shell scripts and use those to interact with the Messenger API. Perfect if you don't want to start involving developers.
Integration Examples
We've put together some simple examples illustrating how to use the /api/3/sms/out API to send a message using a number of popular programming languages: HTML, Java, Objective C, PHP, and Python
API Authentication
Before we allow use of our APIs you must first authenticate yourself, so we know who you are. API calls can be authenticated in a few different ways, but all options are underpinned by SSL/TLS encryption for security.
API Key in an HTTP Bearer token
An API key can be manually created from within Messenger on the My Settings | Api Keys page, by clicking the 'Create' menu item.
Make sure you copy the key to the clipboard, because you won't be able to access it again. Once you have generated an API Key you use it as a Bearer token in the HTTP Authorization header. eg:
curl -H 'Authorization: Bearer eyJhbG...LBak' https://www.bulletinmessenger.net/api/3/sms/out --data "to=642715414141" --data "body=hi"
Username and Password via HTTP Basic Auth
It is also possible to authenticate your user using HTTP Basic Auth.
curl --user your-user-name:your-password https://www.bulletinmessenger.net/api/3/sms/out --data "to=642715414141" --data "body=hi"
Username and Password in HTTP POST request
curl https://www.bulletinmessenger.net/api/3/sms/out --data "userId=youruser-name" --data "password=your-password" --data "to=642715414141" --data "body=hi"
Sending Messages
Use secure HTTPS GET or POST (recommended) to send messages to https://www.bulletinmessenger.net/api/3/sms/out
Simple API Example
Here’s a simple GET example:
https://www.bulletinmessenger.net/api/3/sms/out?userId=yourId&password=yourPassword&to=64222222221&body=hello%20world
Don’t forget to use your password and an international-format number for the recipient, in the “to” parameter.
The complete list of URL encoded parameters for sending messages are:
| Name | 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. Not valid with Virtual Numbers or Short Codes. | 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 undefined 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. See Callback URLs | NO | /api/3 |
| callbackStatusUrl | Provide an http or https URL to be called when the status of this message changes. See Callback URLs | NO | /api/3 |
Handling a Response
Messenger will respond to each and every HTTP request with one of the following result codes, and an XML response in the body.
| Code | Meaning | Action Required |
|---|---|---|
| 200 | Success! | Message Passed API validation, check the HTTP response XML for details if message subsequently fails Note Messenger versions earlier than /api/3 return 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 companies may be limited in the number of messages sent per day and will get a 403 error if this is exceeded. Contact Support 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.
The body of the response is an XML structure that provides more information about the send attempt.
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:
<?xml version="1.0" ?>
<outbound-message-delivery messageId="FebPromo" isError="true" errorCode="401" errorMessage="Unauthorised">
</outbound-message-delivery>
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".
<?xml version="1.0"?>
<outbound-message-delivery messageId="FebPromo" isError="false">
<recipient msisdn="64211111111" isError="false"/>
<recipient msisdn="64211111112" isError="false"/>
<recipient msisdn="64222222221" isError="true" errorCode="403" errorMessage="Cannot deliver to 64222222221 (Number in Blocked List)"/>
<recipient msisdn="salestem" isError="true" errorCode="403" errorMessage="Cannot deliver to salestem (Contact not in Address Book)"/>
</outbound-message-delivery>
Receiving via Callbacks
Messenger can call URLs you provide when certain events occur. These events are:
- An inbound 'reply' message is received for your organisation.
- The status of an outbound message has changed (e.g. it has been received).
Note that default values can be defined for your organisation from within Messenger, on the API Settings page, and only need to be defined when using the API if they need to vary from the defaults.
Each time an appropriate event occurs, Messenger will call your provided URL.
If your service returns an http result code in the 400+ range we will retry for up to 48 hours. To avoid duplicate messages being posted to your service we recommend you issue an 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 delivery protocols are http POST, https POST, and, for callbackUrl only, mailto.
Callback URLs can include variables that Messenger will populate dynamically at runtime. These are as follows:
| Variable | Purpose | Reply or Status? |
|---|---|---|
| {!messageId} | Indicates the message that this reply is associated with. Either the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Not valid with Virtual Numbers or Short Codes. | Both |
| {!body} | The body of the message that has been received. | Reply |
| {!recipient.msisdn} | The msisdn that has triggered this callback | Both |
| {!recipient.displayname} | The name of the entity that triggered this callback, when available | Both |
| {!status} | The status of the message that was sent to {!recipient.msisdn} | Status |
Some http examples:
http://example.com/sms-reply?msg={!messageid}&from={!recipient.msisdn}&body={!body}
http://example.com/sms-state?msg={!messageid}&from={!recipient.msisdn}&status={!status}
The mailto: protocol supports standard parameters 'Subject' and 'Body':
| 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 |
Some mailto: examples:
mailto://[email protected]?Subject=Message+from+{!recipient.msisdn}&Body={!recipient.displayname}+says:+{!body}
mailto://[email protected]
The http and https response sent to your callbackUrl, called when a message arrives for your Organisation, is available in two different formats. One is based on XML, and the other is an FORM POST format.
The format used in the callback is defined by your Organisation on the Messenger, and are labelled "XMLv3" and "FORMv1".
Handling a Reply callback
When we call your server the data we provide to you depends on the format selected. These properties are:
| XMLv3 Property | FORMv1 Property | Purpose |
|---|---|---|
| messageId | InReplyToId | This is the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Blank if this is not a reply. Not valid with Virtual Numbers or Short Codes |
| receivedDate | n/a | The date the reply message was received, formatted as ISO-8601 in the UTC Timezone |
| displayName | n/a | The human-readable version of the msisdn, if available |
| msisdn | from | The phone number that sent the message. |
| n/a | to | The phone number that Messenger received the message on |
| body | body | The content of the SMS message received from the MSISDN (formatted as CDATA for XML) |
The "XMLv3" reply document is formatted as in the following example:
<?xml version="1.0" ?>
<inbound-message messageId="FebPromo" receivedDate="2012-03-20T01:36:00Z">
<recipient displayName="Big Bob" msisdn="6421333333">
<body><![CDATA[Thanks for that]]></body>
</recipient>
</inbound-message>
The "FORMv1" reply document is simply an http post containing the following form properties, as described above:
- messageId
- to
- from
- inReplyToId
- body
Handling a Status callback
The data available in the status callback depends on the format selected. These properties are:
| XMLv3 Property | FORMv1 Property | Purpose |
|---|---|---|
| messageId | InReplyToId | This is the messageId value returned in the /api/3/sms/out call, or a UUID allocated automatically by Messenger if /api/3/sms/out was not used. Blank if this is not a reply. Not valid with Virtual Numbers or Short Codes. |
| to | to | A MSISDN or Short Code from Bulletin's threading range |
| from | from | The number of the handset that the status change is associated with. e.g. Who received the message. |
| statusCode | statusCode | See Message Status Codes for simple descriptions of Codes used. |
| statusDate | n/a | The date the status message was received, formatted as ISO-8601 in the UTC Timezone |
| statusId | messageId | A unique identifier for this status message. Check this ID to ensure you have not already processed this status update. |
| error | error | More readable information about the Message Status, when available. |
The "XMLv3" status document is formatted as in the following example:
<?xml version=\"1.0\" ?>
<status-update>
<messageId>summerpromo76</messageId>
<to>4040</to>
<from>021333333</from>
<statusCode>RCV</statusCode>
<statusDate>2012-03-20T01:36:00Z</statusDate>
<statusId>9182</statusId>
<error></error>
</status-update>
The "FORMv1" reply document is simply an http post containing the following form properties, as described above:
- messageId (please note that this is, unfortunately, the same as the XMLv3 property "statusId", not the XMLv3 property "messageId")
- to
- from
- statusCode
- inReplyToId
- error
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
Using Callbacks in the API
The API allows Callback URLs to be defined individually when each message is sent, which is useful if you don't wish to use a Company default.
These are defined by API parameters callbackUrl and callbackStatusUrl
When defining these URLs they must be URL encoded prior to inclusion in the request. Here's a walkthrough describing how to define a "mailto:" URL:
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
Subject=Message:%20{!messageId}&Body={!body}%0A%0A--%20%0AIn%20Reply%20to%20{!messageId}%0A%0A
Step 2: Concatenate the mailto string together as below
mailto:[email protected]?Subject=Message:%20{!messageId}&Body={!body}%0A%0A--%20%0AIn%20Reply%20to%20{!messageId}%0A%0A
Step 3: Finally URL Encode the entire string, for use as the "callbackUrl" parameter
mailto%[email protected]%3FSubject%3DMessage%3A%2520%7B%21messageId%7D%26Body%3D%7B%21body%7D%250A%250A--%2520%250AIn%2520Reply%2520to%2520%7B%21messageId%7D%250A%250A
Note: This does result in 'double' encoding of the mailto parameters if used. This is correct and required.
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
Receiving Incoming Messages via Polling
You may obtain information about Messages and Statuses via our Polling API. Polling is 'firewall friendly' and often easier to implement (especially if you are working outside an HTTP server), but for the best experience we recommend Callbacks.
Use secure HTTPS GET or POST (recommended) to receive messages via https://www.bulletinmessenger.net/api/1/sms/in
Simple API Example
Here’s a simple GET example:
https://www.bulletinmessenger.net/api/1/sms/in?userId=yourId&password=yourPassword
Don’t forget to use your login and password
All messages appear in this api – including those that have been notified via callbacks. Each call to this API returns a single unread message and then marks it as read
There are just two URL encoded parameters for polling messages:
| Name | Description | Required? |
|---|---|---|
| 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 |
| password | Your account password | YES |
Messenger 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. |
| 500 | Internal Error | Contact Bulletin |
Polling Delays
Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour
Polling will only transmit unread messages within the Messenger platform and mark them as read once transmitted. Remember this when testing.
For 200 codes (success) Messenger will include a form encoded parameter list containing some or all of message information as described below.
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
| List Item | Description | Notes |
|---|---|---|
| messageId | A unique identifier for the message | Messenger Unique ID. Check this ID to ensure you have not already processed this incoming message. |
| 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 messages only, not to reply messages. |
| inReplyToId | Correlation ID (if the message is a reply) | Matches the messageId returned to you in the response to /api/3/sms/out. 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 (or virtual number) as they are still considered MO messages. |
| body | Message Content | URL encoded content of the user's message |
| messageDate | The Date that the message is received | Formatted as ISO-8601 in the UTC Timezone, for example: 2017-05-16T01:23:04.417Z |
| contentType | The content type used in the message | text/plain, or text/plain; charset=UTF-16 |
Example GET Request
Substitute your correct Messenger Credentials in this example and if you have any unread incoming messages available then you will download one of them if you access the URL in a browser.
https://www.bulletinmessenger.net/api/1/sms/in?userId=yourUserID&password=yourPassword
Example Mobile Initiated Message Content
This shows the content of the request when the messages is not a reply but is an 'MO messages' message (ie: initiated by the handset).
Note: the to value is included in the content while the inReplyToId is not included.
body=Play+the+eagles+long+run&contentType=text%2Fplain&from=6149123456&messageId=3685355&to=4040&messageDate=2017-05-16T01%3A23%3A04.417Z
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=3685355
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=3685355
Handy Hint
To take advantage of 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. You can not receive specific messages/replies using the API. Access the https://www.bulletinmessenger.net web site to view your incoming messages or use the Message Feed to access your Inbox using your code/application.
Receiving Outgoing Messages via Polling
You may obtain information about Messages and Statuses via our Polling API.
Use secure HTTPS GET to receive messages via https://www.bulletinmessenger.net/api/3/sms/out/poll
Simple API Example
Here’s a simple GET example:
https://www.bulletinmessenger.net/api/3/sms/out/poll?userId=yourId&password=yourPassword
Don’t forget to use your login and password
All messages appear in this api. Each call to this API returns a list of messages sent since last polling date and then last polling date is updated with the latest polling date.
There are just two URL encoded parameters for polling messages:
| Name | Description | Required? |
|---|---|---|
| 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 |
| password | Your account password | YES |
Messenger 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 outgoing message details as described below. |
| 401 | Unauthorized | Check userId and password. |
| 500 | Internal Error | Contact Bulletin |
For 200 codes (success) Messenger will include JSON response containing some or all of message information as described below.
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
| List Item | Description | Notes |
|---|---|---|
| messageId | A unique identifier for the message | Messenger Unique ID. Check this ID to ensure you have not already processed this outgoing message. |
| body | Message Content | The user's message |
| recipientCount | Number of recipients | |
| recipients | Recipients | A string containing a summary of the recipients, for example: Bob, Mary + 7 others |
| messageDate | The Date that the message is received | Formatted as ISO-8601 in the UTC Timezone, for example: 2017-05-16T01:23:04.417Z |
| statusCode | A summarised delivery status of the message. For an accurate status consult the 'recipientsList.statusCode' | See Message Status Codes for simple descriptions of Codes used. |
| deleted | Flag to identify if deleted | Indication flag whether the message is deleted or not |
| recipientsList | List of recipients | |
| recipientsList.from | Source address | The sender of the message in International format. |
| recipientsList.to | Destination address | The address the message was sent to. Applies to MT messages messages only, not to reply messages. |
| recipientsList.name | Recipient name | The name of the person who receives the message |
| recipientsList.statusCode | The delivery status of the message | See Message Status Codes for simple descriptions of Codes used. |
| recipientsList.channel | Channel | The method used to deliver the message, i.e. Sms |
Example GET Request
Substitute your correct Messenger Credentials in this example and if you have any outgoing messages available then you will download a list of them if you access the URL in a browser.
https://www.bulletinmessenger.net/api/3/sms/out/poll?userId=yourUserID&password=yourPassword
Receiving Status via Polling
Clients can GET incoming receipts (status updates) from https://www.bulletinmessenger.net/api/1/sms/status
Clients can be advised of incoming receipts (status updates) via HTTPS GET or POST (recommended) calls https://www.bulletinmessenger.net/api/1/sms/status
Simple API Example
Here’s a simple GET example:
https://www.bulletinmessenger.net/api/1/sms/status?userId=yourId&password=yourPassword
Don’t forget to use your login and password
There are just two URL encoded parameters for polling messages:
| Name | Description | Required? |
|---|---|---|
| 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 |
| password | Your account password | YES |
Messenger 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. |
| 500 | Internal Error | Contact Bulletin |
Polling Delays
Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour
Polling will only transmit unread messages within the Messenger platform and mark them as read once transmitted. Remember this when testing.
For 200 codes (success) Messenger will include a form encoded parameter list containing some or all of message information as described below.
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
| List Item | Description | Notes |
|---|---|---|
| messageId | A unique identifier for the message | Messenger Unique ID. Check this ID to ensure you have not already processed this status update. |
| to | A MSISDN or Short Code from our threading range | |
| from | Destination MSISDN of message | The recipient number of an outbound message sent by you in International format. |
| statusCode | Message status | See Message Status Codes for simple descriptions of Codes used. |
| inReplyToId | Correlation ID of the message | Matches the messageId returned to you in the response to /api/3/sms/out. If no messageId was set when you submitted the original message then this will contain 'default'. Not valid with Virtual Numbers or Short Codes. |
| error | Descriptive text | More, readable information about the Message Status |
Recent Message RSS Feed
You may wish to view your recent messages in an RSS Reader, or your own custom application.
Use secure HTTPS GET or POST to view such messages via https://www.bulletinmessenger.net/api/2/sms/list in either RSS or ATOM format.
API Feed Parameters
Recognised URL encoded parameters for retrieving messages are:
| Name (case sensitive) | Valid Values | Description | Required? |
|---|---|---|---|
| userId | String | 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 |
| password | String | Your account password. | YES |
| format | "ATOM" or "RSS" | Result format | NO. Default feed format is ATOM 1.0 |
| type | "out" or "reply" | The type of messages to return | NO. By default we return both out and reply |
| size | Integer | The maximum number of messages to return. Note that no more than 300 messages will be returned. | NO. Defaults to 8 |
Your application should parse the resulting XML feed and display or manipulate your recent messages.
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 Example#
https://www.bulletinmessenger.net/api/2/sms/list?userId=yourUsername&password=yourPassword&format=ATOM&type=reply&size=20
To view an example of an ATOM feed, click here. To view an example of an RSS feed, click here.