Boomerang REST API Specification.

Transcription

REST API v1.0 Specification &
Integration Guide
Author
Document Version
Date
Andy Allen
1.0
th
10 February 2014
Legal Notices
The contents of this document are strictly confidential and should not be disclosed to any
third party without the prior written consent of Boomerang. Distribution in any form with
regard to this document will be controlled by Boomerang.
REST_API_v1.0_specification_and_integration_guide_v1.0.docx
17-Feb-14
Page 1 of 46
Contents
1
Context ....................................................................................................................................... 5
1.1
Boomerang – Intelligent SMS ....................................................................................... 5
2
Purpose ...................................................................................................................................... 5
3
Scope .......................................................................................................................................... 6
4
References ................................................................................................................................. 6
5
Definitions .................................................................................................................................. 7
6
Preparing for integration ........................................................................................................... 8
6.1
Connectivity settings..................................................................................................... 8
Proxy servers ................................................................................................................. 8
Email messages sent via method ‘SendEmailMessage’ ................................................ 8
6.2
API Security ................................................................................................................... 8
6.3
Data security ................................................................................................................. 9
6.4
Account settings ........................................................................................................... 9
API Key .......................................................................................................................... 9
Username and Password .............................................................................................. 9
6.5
7
Workflow design ......................................................................................................... 10
Structure of the REST API......................................................................................................... 11
7.1
Overview and REST principles ..................................................................................... 11
7.2
Endpoint ...................................................................................................................... 11
Username and Password authentication.................................................................... 11
Structure of Requests ................................................................................................. 12
7.3
8
Error handling ............................................................................................................. 12
Messaging solutions and communication channels ................................................................ 13
8.1
Overview ..................................................................................................................... 13
8.2
Messaging solutions.................................................................................................... 13
Threaded messaging ................................................................................................... 13
Conversational messaging .......................................................................................... 13
Simple 2-way messaging ............................................................................................. 13
One-way messaging .................................................................................................... 14
Summary of messaging solutions with associated methods ...................................... 15
8.3
Message tickets........................................................................................................... 15
17-Feb-14
Page 2 of 46
8.4
Message ticket validity................................................................................................ 15
Overview ..................................................................................................................... 15
Rules associated to message ticket validity ................................................................ 15
Message validity with single and open tickets ........................................................... 16
8.5
Communication channels ........................................................................................... 16
SMS Messaging ........................................................................................................... 17
Voice Messaging ......................................................................................................... 17
8.6
Methods used to process SMS messages ................................................................... 18
Example request ......................................................................................................... 18
Example Response ...................................................................................................... 18
Methods in this section .............................................................................................. 18
SendThreadedMessage............................................................................................... 19
8.7
Methods used to process email messages ................................................................. 22
8.8
Methods used to process voice messages.................................................................. 24
9
10
Message states for each communication channel .................................................................. 26
9.1
Overview of message delivery states for SMS ............................................................ 26
9.2
Overview of message delivery states for email messages.......................................... 27
9.3
Overview of message delivery states for voice messages .......................................... 27
Methods used to query message data .................................................................................... 28
10.1
Elements of an outbound message object ................................................................. 28
10.2
Methods used to query outbound message data....................................................... 29
Method(s) in this section ............................................................................................ 29
10.3
Methods used to query recipient responses .............................................................. 30
Elements of a response object.................................................................................... 30
Method(s) in this section ............................................................................................ 31
10.4
Retrieving recipient responses via ‘Push’ ................................................................... 32
Push to a URL .............................................................................................................. 32
Push to email .............................................................................................................. 32
11
Specification for fixed inbound services .................................................................................. 33
11.1
Overview ..................................................................................................................... 33
11.2
Summary of inbound identifiers ................................................................................. 33
17-Feb-14
Page 3 of 46
11.3
Retrieving message data from inbound identifiers: Push service .............................. 33
Push to a URL .............................................................................................................. 33
Retry process for push service .................................................................................... 34
Push to email .............................................................................................................. 34
11.4
Retrieving data from inbound identifiers: Pull service ............................................... 34
Elements of an inbound object ................................................................................... 34
12
11.5
Automated response messages .................................................................................. 35
11.6
Provisioning inbound services .................................................................................... 36
Methods used to update the status of message data ............................................................. 37
12.1
Methods used to mark data as read ........................................................................... 37
12.2
Methods used to close message transactions ............................................................ 38
13
Methods used to query account status ................................................................................... 39
14
Support .................................................................................................................................... 40
15
Appendix 1 – Message characteristics ..................................................................................... 41
15.1
GSM 03.38 Encoding ................................................................................................... 41
15.2
Unicode messages (UTF-16 encoding) ........................................................................ 42
15.3
Concatenated messaging restrictions ......................................................................... 42
16
Appendix 2 – Error codes ......................................................................................................... 43
17
Appendix 3 – List of country codes .......................................................................................... 44
18
Appendix 4 - Summary of API methods ................................................................................... 46
17-Feb-14
Page 4 of 46
1 Context
1.1 Boomerang – Intelligent SMS
Boomerang’s patented technology enables any mobile device to be integrated into business
processes. Embedding intelligent communications into workflow empowers organisations to
complete stakeholder transactions automatically, increasing choice and reducing costs.
Boomerang's technology matches outbound messages with their associated inbound
responses, irrespective of the quantity and sequence of the messages and without the need
for complex and error prone identifiers in the body of the message.
Boomerang’s multiplexing logic uses:


A combination of senders ID, recipients ID and message validity period to utilise and
optimise a pool of Boomerang Communication Identifier Values (BCIV): which
coordinates the routing and the subsequent matching of inbound responses to the
outbound message
Performance and cost factors to determine the routing of the outbound message.
Boomerang has a number of service features which enhance and add-value to the default
Boomerang solution in the areas of security, personalisation and localisation.
2 Purpose
This document is intended to assist developers who wish to use the Boomerang HTTPS
REST API to implement one-way, 2-way and/or 2-way threaded communication via SMS,
Email or voice and is particularly aimed at developers who are familiar with the following
technologies:








.NET
HTML
Java
Perl
PHP
ASP
Ruby
Python
17-Feb-14
Page 5 of 46
The document is divided into three core sections:



Preparing for integration – This section defines the pre-requisites for a successful
integration.
The API specification – This section describes the various programming methods
and commands available when using the API for each communication channel. This
section is divided into:
o An overview of the message delivery process
o Structure of the REST API
o Messaging solutions and communication channels
o Methods used to process SMS messages
o Methods used to process Email messages
o Methods used to process voice messages
o Methods used to retrieve outbound message data
o Methods used to retrieve response data
o Methods used to retrieve end user initiated inbound message data
o Methods used to update the status of message data
Support – This section describes the process for raising support queries.
3 Scope
This document is intended for technical architects and designers who wish to implement the
Boomerang services on behalf of an organisation using REST. It can be used in conjunction
with any of Boomerang’s available sample projects. Sample projects are available on
request.
Developers preferring to implement services using SOAP should refer to Boomerang’s API
Specification & Integration Guide for SOAP.
4 References
This document is designed to be read in conjunction with the Boomerang Service
Description document. All hyperlinks in this document are in light blue text and underlined.
17-Feb-14
Page 6 of 46
5 Definitions
NAME
SHORT DESCRIPTION
API/License Key
Unique service key consisting of 35 characters which is
used to authenticate API requests.
An automated reply by SMS that is triggered by a
message sent into a long (virtual) number which is
automatically returned to the sender of that message.
Boomerang feature which guarantees that SMS are sent
from a number that is local to the recipient.
A registered Boomerang customer utilising the Boomerang
API for message delivery.
The status of an SMS that is generated after Boomerang
has accepted a message for delivery.
The sender Id for an SMS message that is displayed in the
recipient’s handset inbox.
MSISDN that initiates communications to a Fixed Inbound
Number via a mobile originated (MO) message
A long or short number directly associated to a customer’s
service account which is used to receive inbound
communication initiated by an end user or responses to
non-threaded communication which has been initiated
from the inbound number. Where a Fixed Inbound
Number is used as the sender Id for an outbound
message, any responses to such messages are not
tracked back to the original outbound message.
A unique identifier directly associated an inbound number
used to receive inbound communication from a recipient
as defined above.
A number or range of numbers that are used as the
sender Id exclusively by a single customer.
Simple Mail Transfer Protocol. Method by which email
messages are transmitted over the internet
A number automatically selected by Boomerang which is
used as the sender Id for threaded SMS. This number
also fields replies which are tracked back to the original
outbound message.
The period over which a message will remain “live” before
expiring which is determined by the validity period
associated to it.
A Boomerang feature that enables a recipient to return
multiple responses to the same sender Id.
A registered Boomerang partner utilising the Boomerang
API for message delivery.
Unique alpha numeric string consisting of at least 8
characters used to validate an API request that is created
on registration of a Boomerang account.
Auto-reply message
Boomlocal
Customer
Delivery status
Dynamic header
Recipient
Fixed Inbound Number (FIN)
Keyword
Exclusive number(s)
SMTP
System Virtual number (SVN)
Message validity period
Open ticket
Partner
Password
Recipient
Username
MSISDN receiving a mobile terminated (MT) message
from Boomerang
Unique value used to validate an API request that is
created on registration of a Boomerang account.
17-Feb-14
Page 7 of 46
6 Preparing for integration
Before using this guide we recommend that you have addressed the following:
6.1 Connectivity settings
Boomerang requires any local firewall policies to allow IP transit over HTTPS (443) or
directly to our API.
Where port 443 is blocked for all outbound traffic, please make an exception for the IP
address 46.20.235.141. Please also ensure that any local firewall ACL’s are updated to
allow outbound HTTPS traffic to the network block and port below:
CIDR: 46.20.235.141
Network: 46.20.235.141
Netmask: 255.255.255.255
Port: 443 HTTPS
Proxy servers
Where the service is implemented via a proxy server please ensure that this is also
configured with the appropriate connectivity settings.
Email messages sent via method ‘SendEmailMessage’
Email messages are sent using the domain @boomerangicomms.com. It is therefore
important to ensure that traffic from this domain is allowed through any spam filters.
6.2 API Security
Boomerang is secured using the industry standard 128 or 256 Bit SSL technologies. The
API is encrypted over HTTPS and will also accept requests originating over HTTP. To
implement an efficient and problem free SSL transit to the Boomerang platform, please
ensure that your local Certification Authority (CA) trusted SSL root store contains the Go
Daddy Class 2 CA.
In the event that your trusted SSL store does not contain Go Daddy Class 2 CA please
contact our technical support team. Details of how to raise support tickets are provided in
the Support section of this document.
17-Feb-14
Page 8 of 46
6.3 Data security
Any organisations needing to guarantee the integrity of transactional message data can
request that sensitive elements of the data are made obsolete. Boomerang provides the
ability to purge any or all of the following:



Message content for all outbound messages
The destination address (mobile number, email address etc) for outbound messages
Message content contained in mobile originated messages
The point at which the data is purged can be specified as follows:



Immediately after a message has been processed / received
After the data has been retrieved over the API
After a pre-defined number of days
6.4 Account settings
Before an application or service can send and receive messages, a Boomerang service
account is required.
On creation of the service account, an API key is automatically generated along with a
username and password – these credentials are required for a request to the API to be
successfully authenticated. An email containing this information is sent to the designated
contact name that is provided as part of the account registration process.
API Key
This is a unique service key that is issued to a new account and must be passed in all
requests made to the API. The key is 35 characters e.g. “YWDZ8-H5942-KAX2G-R65C4SFA42-6HGNV” and is case sensitive. Access to the API can be controlled by changing
some of the attributes associated to each key e.g. selecting an expiry date so the key is only
valid for a specific number of days. If the system finds the key invalid, access to the API will
be denied and an exception will be returned.
Username and Password
In addition to the API key, a username and password are required so that Boomerang can
identify the specific account within an organisation attempting to access the API. Where
Boomerang fails to validate the account credentials, the request will be denied. Please also
note that if the system is successful in locating the account and that account is locked or
deleted, the request will also be denied.
The Username and Password are authenticated via an HTTP header (using simple
authentication). The Username and Password are not submitted alongside the other FORM
POST variables.
17-Feb-14
Page 9 of 46
To request an account, contact the Boomerang Operations team by either:
Email
Telephone
support@boomcomms.com
+44 (0)20 7224 5555
Customer
Active Customer Account &
API key for Boomerang
Boomerang APIs
Customer Firewall Port 443
Permitted to 46.20.235.141
Boomerang SSL Cert
Root CA Certificate Trust
Enabled Go Daddy
Figure 1: Overview of requirement for integration with Boomerang service
6.5 Workflow design
The functionality contained in Boomerang’s API has been developed to facilitate a wide
range of workflow ‘use cases’. The ‘Boomerang Service Description’ provides examples of
some of these use cases. If you have not already received this document it is available on
request by contacting operations@boomcomms.com.
This API specification provides a description of the methods available which can be used
during composition of workflow.
17-Feb-14
Page 10 of 46
7 Structure of the REST API
7.1 Overview and REST principles
The Representational State Transfer (REST) architecture describes how clients can make
requests to a server on a set of defined ‘resources’ and get an appropriate response back.
REST uses basic HTTP method verbs to specific resource URLs (uniform resource
identifier):
The use of these verbs describes operations on a resource in the following manner:

GET
o Retrieves a representation of the requested resource (current state)

POST
o Create a new instance of a resource

PUT
o Update an existing instance of a resource

DELETE
o Remove an existing instance of a resource
7.2 Endpoint
All communication via the REST API adheres to the following structure:
https://api.boomerangicomms.com/rest/MethodName
For example, the method ‘SendTextMessage’ would look like this:
https://api.boomerangicomms.com/rest/SendTextMessage
Username and Password authentication
The Username and Password are authenticated via an HTTP header (using simple
authentication). The Username and Password are not submitted alongside the other FORM
POST variables. An example is provided below:
POST /rest/SendThreadedMessage HTTP/1.1
Authorization: Basic YW5keTpwXYNzd29yZA==
Host: api.boomerangicomms.com
Accept: */*
Content-Length: 302
Content-Type: application/x-www-form-urlencoded
17-Feb-14
Page 11 of 46
Structure of Requests
The Boomerang API uses the standard HTTP POST method to interact with a set of defined
resources. Submitted requests are sent via HTTP Form POST variables and responses from
the API are UTF-8 encoded XML representations
Below is an example request to the “SendThreadedMessage” function:
licenseKey => 11111-22222-33333-44444-55555-66666
recipientsMobileNo => 447508xxxxxx
campaignName => My Campaign
conversationId => My Conversation
customIdentifier => my ID
textMessage => My text message
autoResponseMessage =>
validityPeriod => 24 hour
isOpenTicket => No
emailResponsesTo =>
source =>
7.3 Error handling
To help a customer identify and resolve runtime errors, when an exception occurs, the API
will return a mnemonic code and a human-readable message. The code and the message
will be different depending on the type of error. The example below shows an ‘Invalid User’
error being returned:
<Error>
<ErrorCode>400</ErrorCode>
<ErrorText>Invalid user</ErrorText>
</Error>
For a full list of error codes and their corresponding messages, please click Here.
17-Feb-14
Page 12 of 46
8 Messaging solutions and communication channels
8.1 Overview
The objective of this specification document is to define all of the functions contained in the
REST API and assist the user in selecting the methods which are most appropriate to the
type of service to be implemented. The core outbound messaging solutions and
communication channels (SMS, Email and Voice messaging) are summarised in this section
and covered in greater detail later in the document.
8.2 Messaging solutions
There are a number of ways by which an organisation can interact with its stakeholders,
which is determined by the API method selected for the send. Each messaging solution is
described below:
Threaded messaging
Threaded communication is at the core of Boomerang’s (patented) functionality and uses the
‘SendThreadedMessage’ function. When called, this function automatically selects a
Boomerang System Virtual Number (SVN) as the sender Id for a message; which enables
multiple concurrent outbound messages to be matched with their associated responses,
irrespective of quantity and order. A unique message Id is automatically generated by
Boomerang and is included the initial response ‘handshake’ on receipt of a message
request. Boomerang also allows a bespoke identifier to be used to allow a customer to track
messages when connecting via the API. Each message will be sent using SVN’s owned by
Boomerang and a recipient can respond to each message independently.
Conversational messaging
Boomerang allows a service or application to engage in a ‘conversation’ with a recipient
using the ‘preferredMobileNo’ parameter within the ‘SendThreadedMessage’ function. The
parameter allows the same VN to be passed as the sender Id for all messages within a
particular ‘conversation’. This will ensure that a conversation ‘string’ is maintained in the
recipient’s mobile device (i.e. all messages arrive from the same Boomerang number and
are chronologically displayed as part of the conversation within that number). Where
multiple simultaneous conversations are required to the same recipient, different VNs can be
used to manage each conversation. Where Boomerang identifies a ‘preferred’ number that
is already is ‘active’ (in use with a recipient), the next available sequential number will be
selected.
Simple 2-way messaging
Simple 2-way messaging uses the ‘originatingMobileNo’ parameter of the
‘SendTextMessage’ function; which allows a bespoke number to be passed as the sender Id
for a message. Where a bespoke number external to the Boomerang solution is used,
responses are not stored in the Boomerang platform. Where either a Fixed Inbound Number
or a System Virtual Number (both of which reside in the Boomerang solution) are used as
the message originator, responses are therefore stored in the
17-Feb-14
Page 13 of 46
Boomerang solution and can be retrieved via the API or pushed to a URL. However,
responses to messages sent using the ‘originatingMobileNo’ are NOT tracked against the
original outbound message (i.e. these are not threaded messages) and do not have a
validity period associated to them. It is also possible to ‘push’ these responses to a specific
URL or email address.
One-way messaging
When a message is sent using a Dynamic Header as the sender Id, rather than showing a
System Virtual Number, a user configurable alphanumeric code, (e.g. company name) is
displayed in the handset inbox. This communication type requires the parameter
‘dynamicHeader’ to be passed within the method ‘SendTextMessage’. A recipient cannot
respond to a message sent using a Dynamic Header.
Figure 7 details the typical message flow associated with each of the methods for sending
and receiving messages:
Figure 7: Methods of interaction with recipients
*Note regarding these communication types:
When delivering messages into some destinations (most notably the US & Canada),
Boomerang is required to use a local VN as the originator for this message. As such, not all
communication types are available in these destinations.
17-Feb-14
Page 14 of 46
Summary of messaging solutions with associated methods
The table below defines the API methods used to achieve each messaging solution offered
by Boomerang:
Messaging solution
One-way messaging (Dynamic header)
SThM
STM
Simple 2-way messaging (Originating No.)
Conversational messaging (Preferred No.)
Threaded messaging
Key to methods in table above:
 SThM = SendThreadedMessage
 STM = SendTextMessage
The parameter required within each method is stated in brackets.
8.3 Message tickets
Boomerang provides the capability to issue two different types of 2-way messaging tickets
when sending threaded messages; they are defined as follows:


Single ticket
o A single ticket / message is automatically closed on receipt of the single
requested response message.
Open ticket
o An open ticket / message is issued to an end user and allows an end user to
return multiple response messages to the same outbound message request.
8.4 Message ticket validity
Overview
All ‘threaded’ messages sent through Boomerang will have a validity period associated to
them. Message validity governs the lifespan of a message ticket, i.e. the message validity is
calculated from the point that Boomerang sends the message and will automatically expire
upon reaching the designated validity period associated to it. Message validity is selected
on purchasing Boomerang services and the subscription selections are as follows:
1 hour, 2 hours, 6 hours, 12 hours, 24 hours, 48 hours, 96 hours, 1 week or 2 weeks.
Rules associated to message ticket validity
When processing message requests please consider the following:

The parameter can be entered using upper or lowercase or a combination of the two.

It is possible to pass a request with any validity value up to the maximum period
associated to the account, providing that the value passed is a whole number.
17-Feb-14
Page 15 of 46
For example, an account with a validity period of 24 hours can pass a request with a
validity period ranging between 1 hour and 24 hours.

Where the validity value passed exceeds the maximum associated to the account, the
maximum validity value will be passed with that request.

Boomerang can accept requests in different denominations of time. For example, a
message set to expire in two days could be passed as ‘2 Days’ or ’48 Hours’.

All requests must be passed with a validity period that is greater than one hour.
Message validity with single and open tickets
A single ticket will close on receipt of a response from the recipient or on the expiry of the
validity period – whichever occurs first. Single tickets can be manually closed by the
workflow process before a recipient responds by using the appropriate API function.
An open ticket will close on expiry of the validity period or through a manual close initiated by
the workflow process by using the appropriate API function.
8.5 Communication channels
The API offers omni-channel messaging using SMS, email and voice. The table below
defines the messaging solutions (described in the section above) supported across each
communication channel.
Threaded
Conversational
Simple 2-way
One-way
SMS
Email
Voice
This section describes the process of delivering messages across each communication
channel and focuses on the specific attributes for each.
17-Feb-14
Page 16 of 46
SMS Messaging
Boomerang has partnered with multiple tier 1, SMS carriers guaranteeing that our message
service is reliable and efficient. Through the use of multiple upstream partners we can
dynamically route between carriers to optimise the quality of service delivery. Each of these
carriers has multiple routes in place, allowing them to reach almost all network operators
across the globe. There are a number of stages (handshakes) included in the process of
delivering a message. These are illustrated below:
Email Messaging
Boomerang uses Simple Mail Transfer Protocol (SMTP) to transmit email messages over the
internet. The clustered and fault tolerant Boomerang VmWARE cloud provides geographical
redundancy for all inbound SMTP traffic between two split locations, Manchester UK and
London.
Inbound SMTP traffic is routed into the Boomerang platform via a set of clustered DNS
services which in turn route SMTP traffic toward the code Boomerang service layer.
The Boomerang service in turn performs SMTP routing (both inbound & outbound) at its core
cloud layer, thus ensuring full fault tolerance.
In the unlikely event of a network / routing issue upstream, traffic is dynamically re-routed to
our alternative location thus ensuring 100% service availability for both DNS & SMTP
services.
Voice Messaging
Boomerang has partnered with multiple voice carriers to implement a redundant service
supporting delivery of voice messages to both fixed line and mobile telephone numbers.
17-Feb-14
Page 17 of 46
8.6 Methods used to process SMS messages
The methods described in this section enable single or batched SMS message requests. A
valid licence key, username and a password must be provided with all requests and all
parameters are case sensitive.
Example request
The example below shows the structure of a request to the ‘SendThreadedMessage’
method:
licenseKey => 11111-22222-33333-44444-55555-66666
recipientsMobileNo => 447508xxxxxx
campaignName => My Campaign
conversationId => My Conversation
customIdentifier => my ID
textMessage => My text message
autoResponseMessage =>
validityPeriod => 5 hour
isOpenTicket => No
emailResponsesTo =>
source =>
Example Response
The response returned after sending a message consists of a single transaction record or a
number of transaction records matching each destination number or address included in the
request. An example is provided below:
<transactions>
<transaction>
<mobileNo>44750813xxxx</mobileNo>
<transactionId>2684</transactionId>
</transaction>
<transaction>
<mobileNo>44750813xxxx</mobileNo>
<transactionId>2685</transactionId>
</transaction>
</transactions>
Methods in this section
POST Operations


SendThreadedMessage
SendTextMessage
17-Feb-14
Page 18 of 46
SendThreadedMessage
Threading messages
This is the core function used to ‘thread’ SMS messages. Threading is the process that
matches outbound messages with their responses and uses Virtual Numbers to manage this
process.
If a recipient responds to a single ticket message or the validity period for the message has
elapsed, the same System Virtual Number (SVN) will be re-used for any further messages to
that recipient. If not, a different SVN (usually the next sequential number) will be used. This
ensures that all responses are matched to the specific outbound email message.
For Open Ticket messages, the validity period for a message must have elapsed before a
System Virtual Number number is re-used when sending to the same recipient.
Using a ‘preferred’ system virtual number
This function also offers the ability to specify a preferred virtual number, which is used in
preference to the System Virtual Number that is selected by Boomerang. The purpose of
this method is to ensure that, where required, communication with a recipient originates from
the same SVN (this is especially important where multiple concurrent ‘conversations’ are
taking place with the same recipient). As mobile devices will always display a chronological
record of communications according to the sender Id associated to a message, this
parameter ensures the service or application can maintain continuity by setting the required
SVN. Consequently, a recipient can quickly identify messages relating to a specific
‘conversation’ based on the number from which they were sent.
NB: Where Boomerang identifies that a recipient already has an ‘active’ message
originating from a number that is passed as part of a request, then the next sequential
system virtual number will be used (where available).
On processing a message request Boomerang automatically returns a system generated
message Id (integer). The message Id can then be used at a later date to query the system
for data relating to a message. Where a customer wishes to track messages using an
identifier generated by their own application, a bespoke reference may be passed within the
‘customIdenitifier’ parameter.
Below is a description of each parameter available with this method:
Parameter
Mandatory Description
/ Optional
username
M
password
M
licenseKey
M
Boomerang account username. This is unique for every
account in the system and is a mandatory, case sensitive
field.
Boomerang account password. A password must contain: a
minimum of 8 characters, at least one upper and lower case
character and one digit. This is a case sensitive field.
A unique API key is automatically generated on creation of
every Boomerang account. Consisting of 35 characters, the
API key adheres to the following format: XXXXX-XXXXX-
17-Feb-14
Page 19 of 46
preferredMobileNo
O
recipientsMobileNo
M
campaignName
O
customIdentifier
O
text
M
conversationId
O
autoResponseMessage
O
validityPeriod
M
isOpenTicket
O
emailResponsesTo
O
Source
O
XXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory,
case sensitive field.
A System Virtual Number that is passed by in the request
and used as the sender Id for a message; replacing a SVN
which is automatically selected by Boomerang. Any
response will be returned to the number passed. Please
note that this selection will be overridden where Boomerang
identifies that a recipient already has an active message
originating from the virtual number passed as part of the
request.
The recipient’s mobile phone number which must contain a
minimum of 10 digits and a maximum of 20 digits (excluding
a + where this is used as a pre-fix to the number itself). A
single number or an array of up to 50 numbers can be
passed.
Optional Identifier which can be used to group messages by
specific campaigns.
A value generated by the customer’s application which can
be associated to a single message or to multiple messages.
If this is not required pass null or an empty value.
The content of the message to be sent to the recipient.
Messages over 160 characters in length are received as a
single message although messages will be billed on number
of blocks with 160 characters*. Please refer to Appendix 1
for further information regarding message characteristics
and supported character sets.
A parameter that is used to track a conversation between
your application and the recipient. If this is not required
pass null or an empty value.
Where provided, an auto-response message will
immediately sent to a recipient responding to an original
outbound message. Where not required, pass null or an
empty string.
A mandatory field which determines the message expiry
period. On reaching its expiry the message will be
automatically closed by Boomerang regardless of whether a
response is received from the recipient. The format required
is [NUMBER] [HOURS/DAYS/WEEKS]
A message ticket that is not closed by a recipient’s response
and therefore allows multiple responses to a message. An
open ticket is closed by either the validity expiration or by
using the CloseByMessageId function. This is a mandatory
Boolean function. Set: ‘Yes’, ‘True’ or ‘1’ if required. Leave
blank or set ‘No’ or ‘0’ to submit the message as a single
ticket.
The email address to which a recipient’s response will be
forwarded.
A parameter allowing the customer to enter the originating
application for the message.
Please note that this method should not be used for one-way messaging. Any
messages sent using this function will be charged at Boomerang’s threaded SMS rate.
17-Feb-14
Page 20 of 46
SendTextMessage
This operation can be used to carry out one-way (‘dynamicHeader’ parameter) or simple 2way (‘originatingMobileNo’ parameter) communications.
One-Way messaging
The ‘dynamicHeader’ parameter allows a user configurable alphanumeric code, (e.g.
company name) to be used as the sender Id for a message. This value must be a
maximum of 11 characters and should not contain non-standard characters such as spaces
or underscores. A recipient of a Dynamic Header message cannot respond to it (the
recipient’s device will prevent this and display an error message).
Simple 2-way messaging
The ‘originatingMobileNo’ parameter allows a bespoke number to be used as the sender Id
for a message. The originating number may be external to the Boomerang platform (a user’s
own mobile number for example), in which case it will not be possible to retrieve the
response data from Boomerang. Where the number passed is hosted on the Boomerang
platform (e.g. a fixed inbound number) responses will be stored with Boomerang (and can be
retrieved using the ‘GetInboundMessage’ function); but will NOT be tracked against the
original outbound message. As such, there is no validity period associated to messages
sent using this function and the messages are not threaded.
‘customIdentifier’ parameter.
Parameter
/ Optional
username
M
password
M
licenseKey
M
dynamicHeader
O
originatingMobileNo
O
campaignName
O
Boomerang account username. This is unique for every account
in the system and is a mandatory, case sensitive field.
A unique API key is automatically generated on creation of every
Boomerang account. Consisting of 35 characters, the API key
adheres to the following format: XXXXX-XXXXX-XXXXXXXXXX-XXXXX-XXXXX. This is a case sensitive field.
A user configurable alpha numeric sender Id which must consist
of a maximum of 11 characters. A dynamic header does not
accept spaces. Messages sent with this parameter do not have
a validity period associated to them.
A bespoke number that is used as the sender Id for a message.
Any response will be returned to the number passed but will not
be threaded. Messages sent with this parameter do not have a
validity period associated to them.
specific campaigns.
17-Feb-14
Page 21 of 46
customIdentifier
O
recipientsMobileNo
M
text
M
source
O
A value generated by the customer’s application which can be
associated to a single message or to multiple messages. If this
is not required pass null or an empty value.
The recipient’s mobile phone number. This must contain a
minimum of 10 digits and a maximum of 20 digits (excluding a +
where this is used as a pre-fix to the number itself)
Messages over 160 characters in length are received as a single
message although messages will be billed on number of blocks
with 160 characters. Please refer to Appendix 1 for further
information regarding message characteristics and supported
character sets.
Please note that this method is not available for:

Customers delivering messages within North America (unless these messages are
using a fixed inbound number which has been provided by Boomerang and is local to
the USA).
8.7 Methods used to process email messages
The methods described in this section enable single or batched email message requests. A
valid licence key, username and a password must be provided with all requests. All

SendEmailMessage
SendEmailMessage
This function can be used to thread email message conversations between an application
and email recipient. Email messages are always sent from an address which is generated
automatically by Boomerang when processing the request. The email address used
adheres to the following structure: <messageId@boomerangicomms.com> and ensures that
all responses are matched to the relevant outbound email message.
Using the ‘From’ parameter, it is also possible set a ‘sender Id’ value that is displayed in the
inbox of the recipient’s email client. This allows the recipient to ‘sort’ messages in their inbox
based on the sender Id passed in the request.
17-Feb-14
Page 22 of 46
Parameter
/ Optional
username
M
password
M
licenseKey
M
recipientsEmail
emailFrom
M
O
emailSubject
campaignName
O
customIdentifier
O
text
M
conversationId
O
autoResponseMessage
O
validityPeriod
M
isOpenTicket
O
emailResponsesTo
O
source
O
O
account in the system and is a mandatory, case sensitive field.
A unique API key is automatically generated on creation of
every Boomerang account. Consisting of 35 characters, the
API key adheres to the following format: XXXXX-XXXXXXXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory,
case sensitive field.
The recipient’s email address.
The ‘From’ value displayed in the recipient’s email inbox. Where a
value is not passed, ‘Boomerang’ will be used as the default.
The subject of the email, displayed in the recipient’s email inbox.
specific campaigns.
A value generated by the customer’s application which can be
associated to a single message or to multiple messages. If this
is not required pass null or an empty value.
The content of the message to be sent to the recipient. A limit of
2MB applies to the content of the outbound message.
A parameter that is used to track a conversation between your
application and the recipient. If not required pass null or an
empty value.
Where provided, an auto-response message will immediately
sent to a recipient responding to an original outbound
message. Where not required, pass null or an empty string.
automatically closed by Boomerang regardless of whether a
response is received from the recipient. The format required is
[NUMBER] [HOURS/DAYS/WEEKS]
A message ticket that is not closed by a recipient’s response
therefore allowing a recipient to issue multiple responses to a
message. An open ticket is closed by either the validity
expiration or by using the ‘CloseByMessageId’ function. This is
a mandatory Boolean function. Set: ‘Yes’, ‘True’ or ‘1’ if
required. Leave blank or set ‘No’ or ‘0’ to submit the message
as a single ticket.
forwarded.
It is important to ensure that there are no restrictions in place which may prevent an email
being successfully delivered to a recipient or the recipient’s ability to respond to it. Before
attempting to send emails from Boomerang, please ensure the domain
@boomerangicomms.com is pre-approved (white listed) against any spam filters that are in
place local to the recipient.
17-Feb-14
Page 23 of 46
8.8 Methods used to process voice messages
The methods described in this section enable single or batched voice message requests. A
valid licence key, username and a password must be provided with all requests. All

SendVoiceMessage
SendVoiceMessage
This function can be used to thread voice messages sent from an application to a mobile or
fixed line number. Voice messages are sent from a System Virtual Number (SVN)
automatically selected by Boomerang when processing the request. Where a voice
message is confirmed as ‘delivered’ / ‘acknowledged’ by a recipient or the validity period for
the message has elapsed, the same System Virtual Number will be re-used. If not, a
different System Virtual Number is used for any subsequent messages sent to the same
recipient. This ensures that all responses are matched to the specific outbound voice
message.
Parameter
Mandatory /
Description
Optional
username
M
password
M
licenseKey
M
recipientsMobileNo
M
campaignName
O
customIdentifier
O
account in the system and is a mandatory, case sensitive
field.
Boomerang account password. A password must
contain: a minimum of 8 characters, at least one upper
and lower case character and one digit. This is a case
sensitive field.
A unique API key is automatically generated on creation
of every Boomerang account. Consisting of 35
characters, the API key adheres to the following format:
XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is
also a mandatory, case sensitive field.
The recipient’s destination number which must contain a
minimum of 10 digits and a maximum of 20 digits
(excluding a + where this is used as a pre-fix to the
number itself). A single number or an array of up to 50
numbers can be passed.
Optional Identifier which can be used to group messages
by specific campaigns.
A value generated by the customer’s application which
can be associated to a single message or to multiple
messages. If this is not required pass null or an empty
value.
17-Feb-14
Page 24 of 46
text
M
conversationId
O
validityPeriod
M
emailResponsesTo
O
Source
O
Messages over 160 characters in length are received as
a single message although messages will be billed in
segments of 153 characters. Please refer to Appendix 1
for further information regarding message characteristics
and supported character sets.
A parameter that is used to track a conversation between
your application and the recipient. If this is not required
pass null or an empty value.
automatically closed by Boomerang regardless of
whether a response is received from the recipient. The
format required is [NUMBER] [HOURS/DAYS/WEEKS]
forwarded.
A parameter allowing the customer to enter the
originating application for the message.
Recipients of voice messages will receive an option to confirm receipt of a message or
specifically acknowledge having listened to a message. Where no notification is returned,
an automated delivery retry scheme is invoked. This calls the destination number on two
further occasions, at intervals of ten minutes.
17-Feb-14
Page 25 of 46
9 Message states for each communication channel
The API provides the ability for outbound message data to be retrieved. This provides
access to all message details including an associated delivery state. The potential status
options for each communication channel are defined in this section.
9.1 Overview of message delivery states for SMS
All outbound messages processed by Boomerang will have an associated delivery state or
status. This is dependent on the information received by Boomerang from the message
carriers and network operators. The status of a message is returned as part of the response
data when calling the ‘GetMessageById function’ (defined in the next section). A summary
of the different message delivery states is provided below:

Delivered: A delivery confirmation has been returned by the recipient’s network
operator denoting that the message is delivered to the device. Boomerang will also
update the status of a message to ‘delivered’, when the recipient responds to a
message.

Sent: The message has been successfully processed by Boomerang but has not yet
been delivered. This could be due to, for example:
o The recipient’s handset is switched off at the time delivery was initially attempted
o The recipient’s handset is not registered on the network the time delivery was
initially attempted.
o The recipient’s network operator was experiencing congestion or coverage issues
at the time delivery was initially attempted.
Where messages are not delivered at the first attempt the network operator will
continue to re-attempt delivery for a period of up to 48 hours. The interval between
which delivery is re-tried, varies according to the reason for non-delivery. For
example, where a recipient is overseas and cannot be reached the retry policy will
differ from that where a recipient that is out of network coverage in the UK.
Please note: Where the recipient’s network operator does not support delivery
notifications, a status of ‘Sent’ may still be associated to a message, even though the
message has been successfully delivered. In this scenario Boomerang is unable to
update the status from ‘Sent’ to ‘Delivered’ as no notification from the network
operator is received.

Failed: The message could not be delivered as the recipient’s handset could not be
reached by the network operator. This could be due to:
o The recipient’s handset inbox is full
o The network operator has blocked the inbound message service.
17-Feb-14
Page 26 of 46

Expired: The message could not delivered within the message expiration period
applied by the message carriers / network operators (usually a minimum of 48 hours;
although this varies by destination).

Undeliverable: The message was not processed by Boomerang as the details
provided in the request were invalid or incorrectly formatted.
9.2 Overview of message delivery states for email messages
Boomerang classifies the status of email messages according to the following delivery
‘states’:


Sent: The message has been processed by Boomerang but no further status update
has been received
Delivered: The message has been delivered to the recipient’s inbox (based on
recipient’s reply to the originating message)
9.3 Overview of message delivery states for voice messages

Delivered: The recipient has confirmed receipt of the message via a keystroke entry
prior to listening to the message. On receipt of this keystroke notification,
Boomerang updates the message status to ‘Delivered’.

Acknowledged: The recipient has acknowledged having listened to the message via
a keystroke entry after the message has been played. On receipt of this keystroke
notification, Boomerang updates the message status to ‘Acknowledged’.

Sent: The message has been successfully processed by Boomerang but neither a
delivered or acknowledged notification has been received by Boomerang. Where
messages are not delivered at the first attempt the carrier will continue re-attempt
delivery on two further occasions at intervals of ten minutes.

Failed: The message could not be delivered as the recipient’s device could not be
reached by the carrier.

Expired: The message could not delivered within the message expiration period
applied by the message carriers / network operators (usually a minimum of 48 hours;
although this varies by destination).
17-Feb-14
Page 27 of 46
10
Methods used to query message data
An outbound message is a message which is sent from a service or application to initiate the
engagement process with an intended recipient. The methods in this section describe how
the data elements relating to an outbound message can be retrieved.
10.1 Elements of an outbound message object
The data in the table below is returned when querying outbound message data.
Element
Data
Type
Description
<MessageId>
Integer
<CustomIdentifier>
<CampaignName>
String
String
<From>
<Destination>
String
String
The Id of the message generated by Boomerang which is
automatically returned to the requesting application.
Bespoke message identifier provided by the customer.
Optional Identifier which can be used to group messages into
specific campaigns.
Originating / sender Id associated to a message.
<Text>
<ConversationId>
String
String
<ValidityPeriod>
String
<IsOpenTicket>
Boolean
<AutoResponseMessage>
String
<EmailResponsesTo>
String
<Source>
String
<DateCreated>
<Status>
DateTime
String
<Responses>
Collection
The recipient’s destination address (e.g. telephone number
or email address).
The content of the message sent to the recipient.
A parameter that is used to track a conversation between a
service / application and a message recipient.
The lifespan of a message. On reaching the validity period limit
a message will be automatically closed by Boomerang
regardless of whether a response is received from the recipient.
Denotes whether the message was sent with Open Ticket. An
Open Ticket message ticket is not closed by a response. As
such, multiple responses can be returned. An Open Ticket
message is closed when reaching its validity expiration or can
be closed by calling the ‘CloseByMessageId’ function.
Automated response message to be returned to any recipients
that respond to the message.
Email address to which a recipient’s response will be
forwarded.
A parameter allowing the originating application for the
message to be specified.
The date that the object was created.
The delivery state for a message. The following states are
Delivery states are listed Here
A collection of Response objects. Displayed if a response or
responses have been received
Further information regarding the composition of SMS messages along with a
table containing supported character sets is included in Here.
17-Feb-14
Page 28 of 46
10.2 Methods used to query outbound message data
The method listed in this section provides the ability to retrieve data relating outbound
messages and will return an XML response.
Method(s) in this section
 GetMessage
GetMessage
This operation will retrieve all of the information associated to a single outbound message,
based on the unique message Id. This message Id is generated and returned back to the
originating application after Boomerang has successfully validated the request. This unique
Id must be provided when retrieving message data and the Id must relate to a message
which was sent no longer than 12 months prior to the date that the request is submitted.
Parameter
Mandatory
/ Optional
Description
username
M
password
M
licenseKey
M
messageId
M
Boomerang account username. This is unique for every account in
the system and is a mandatory, case sensitive field.
adheres to the following format: XXXXX-XXXXX-XXXXX-XXXXXXXXXX-XXXXX. This is also a mandatory, case sensitive field.
The id of the message automatically generated by Boomerang and
passed back in the response.
An example response is provided below:
<Message>
<MessageId>2285</MessageId>
<CustomIdentifier>my ID</CustomIdentifier>
<CampaignName>My Campaign</CampaignName>
<From>+44778148xxxx</From>
<MobileNo>+44783666xxxx</MobileNo>
<Text>Test Message</Text>
<ValidityPeriod>1 Hour</ValidityPeriod>
<IsOpenTicket>No</IsOpenTicket>
<EmailReplyTo/>
<Source/>
<DateCreated>2014-01-08T11:51:18</DateCreated>
<Status>Sent</Status>
</Message>
Using the message delivery status
The response returned includes the delivery status of a message (<Status>). On processing
messages Boomerang automatically assigns a status of ‘Sent’ to a message and this status
will remain until Boomerang receives a status update notification from the message carrier.
Based on the notification received Boomerang will update the status to one of the following:
17-Feb-14
Page 29 of 46

Acknowledged (Voice only) / Delivered / Failed / Expired / Undeliverable
Please refer to the section ‘Overview of message delivery states’ for a definition of each
delivery status.
As the status of a message is only ever updated once, to understand the final delivery status
of a message we recommend that this method is used until:


A change of status is identified
48 hours have elapsed since the message Id was returned by Boomerang. This is
the standard duration of the network operator retry policy.
10.3 Methods used to query recipient responses
A mobile originated response is a direct reply to a message originating from the Boomerang
service. Boomerang’s ability to process recipient responses is governed by the following:




A response cannot be retrieved if the original message was sent with a dynamic
header or with a custom number
Messages sent with single ticket will close on receipt of the first reply from a
recipient. Any subsequent replies cannot be matched to the original message ticket
If the original message was sent with the ‘Open Ticket’ feature then the recipient will
be able to send multiple replies
If the validity period of the message has expired Boomerang will be unable to match
the recipient’s response with a message ticket.
One core method is used to retrieve response data and this method contains a number of
parameters that allow the user to update status of the response data (by marking it as ‘read’)
and retrieve data according to its status (‘read’ or ‘unread’).
Elements of a response object
Element
Data
Type
<OriginalMessageId>
Integer
<OriginalMessageIdentifier>
String
<ResponseId>
<RecipientsName>
<Recipient>
<OriginatingFrom>
<ResponseText>
<IsNew>
Integer
String
String
String
String
Boolean
<DateSentToRecipient>
DateTime
<DateOfResponse>
DateTime
Description
The message Id for the original outbound message
which is automatically returned by Boomerang.
The custom identifier provided with the original
outbound message.
The unique Id for the recipient’s response.
The recipient’s full name (where provided)*
The destination address for the outbound message
The sender Id associated to the outbound message
The content of the recipient’s response.
Denotes a response that has not been marked as
‘read’.
The date and time that the recipient received the
message.
The date and time that the recipient’s response was
received by Boomerang.
*Adding recipient data is not currently available.
17-Feb-14
Page 30 of 46
This example illustrates the structure of an XML response containing a collection of
Response Objects.
<Responses>
<Response>
<OriginalMessageId>2896</OriginalMessageId>
<OriginalMessageIdentifier/>
<ResponseId>517</ResponseId>
<RecipientsName/>
<Recipient>447800******</Recipient>
<OriginatingFrom>447781******</OriginatingFrom>
<ResponseText>My reply to your message</Text>
<IsNew>Y</IsNew>
<DateSentToRecipient>2014-02-13T16:58:00</DateSentToRecipient>
<DateOfResponse>2014-02-13T16:58:54</DateOfResponse>
</Response>
</Responses>
Method(s) in this section
 GetResponses
GetResponses
This operation will retrieve all responses that have previously been marked as ‘read’
covering three months prior to the point at which the request is submitted and all ‘New’
(unread) responses covering two days prior to the point at which the request is submitted.
The function also allows response data to be retrieved according to:



messageId (the originating outbound message Id)
clientId (the custom identifier associated to the outbound message)
responseId (the Id associated to the recipient’s response)
Below is a description of all the parameters required for this method:
Parameter
Mandatory
/ Optional
Description
username
M
password
M
licenseKey
M
new
O
markAsRead
O
messageId
O
Will only return responses that have not previously been marked as
‘read’. To set this parameter pass ‘Yes’, ‘1’ or ‘True’.
Will mark all retrieved responses as ‘read’. To set this parameter
pass ‘Yes’, ‘1’ or ‘True’.
The messageId associated to the originating outbound message
17-Feb-14
Page 31 of 46
clientId
O
responseId
O
against which the response was matched.
The customIdentifier associated to the originating outbound
message against which the response was matched.
The Id for the response which is matched to the originating outbound
message.
10.4 Retrieving recipient responses via ‘Push’
This section describes how a recpient’s response can be accessed from a System Virtual
Number as a ‘push’ notification; where data is automatically pushed to a pre-defined
address.
Push to a URL
Boomerang’s push service will automatically forwarda recpient’s response to a destination
URL. The following data is included in the notification:





Date / time of the response
Content of the response
End user’s mobile number
Outbound message Id
Custom identifier (provided in original request)
The URL is manually configured by Boomerang on receipt of a written request. All written
requests should be submitted to operations@boomcomms.com
Push to email
Responses can also be forwarded to an email address. This option cannot be set via the
API and as such all requests are directly managed by Boomerang upon receipt of a written
request. All requests should be submitted to operations@boomcomms.com.
17-Feb-14
Page 32 of 46
11
Specification for fixed inbound services
11.1 Overview
Boomerang’s fixed inbound services allow an end user to initiate communication with an
organisation via SMS or to respond to non-threaded SMS communications which were
previously initiated by an organisation. Inbound services are configured using either a long
or short inbound number, independently or with a keyword (see table below for a description
of each), which must be assigned to your Boomerang account. This extends the opportunity
to integrate Boomerang into workflow using an inbound SMS message as the trigger.
11.2 Summary of inbound identifiers
A description of each type of inbound number is provided below:
Inbound number type
Description
Exclusive long number
A telephone number used to receive SMS messages normally
comprising of eight digits or more which is assigned to a customer on an
exclusive basis e.g. +447860111222
A telephone number used to receive SMS messages normally
comprising of no more than six digits* which is assigned to a customer
on an exclusive basis e.g.60555. Short numbers operate within national
boundaries.
A short number (as defined above) which is assigned on a nonexclusive basis and must be used with a keyword which acts as a
unique identifier for the organisation using the number.
Exclusive short number
Shared short number
(must be used with a
keyword)
*Short numbers native to Australia may contain up to 8 digits
11.3 Retrieving message data from inbound identifiers: Push
service
This section describes how data can be received from an inbound number using a ‘push’
notification service, where the data is automatically pushed to a pre-defined address.
Push to a URL
Boomerang’s push service will automatically forward inbound messages to a destination
URL. The following data is included in the notification:







Date / time of the inbound message
Content of the response
End user’s mobile number
Inbound number
Keyword (if provided)
Inbound Id
Fixed Inbound Number reference (FIN ref)
This URL along with the (optional) username and password are manually configured by
Boomerang on written request from the customer. All requests should be submitted to
operations@boomcomms.com
17-Feb-14
Page 33 of 46
Retry process for push service
Where Boomerang identifies that an inbound message has not been successfully forwarded
to the URL provided a retry process is invoked.
IMPORTANT: On receipt of data at the specified URL, the application receiving the
push notification must be configured to acknowledge receipt of the data by returning
the value ‘OK’.
In the event that an ‘OK’ value is not returned Boomerang will continue to attempt delivery to
the URL as follows:


3 retries immediately after a failure
5 minute intervals thereafter up to 24 hours
Push to email
Inbound messages can also be forwarded to an email address. This option cannot be set
via the API and as such all requests are directly managed by Boomerang upon receipt of a
written request. All requests should be submitted to operations@boomcomms.com.
11.4 Retrieving data from inbound identifiers: Pull service
This section describes the methods by which message data sent to an inbound identifier can
be retrieved from the Boomerang solution by polling or ‘pulling’ the data. Although
Boomerang would recommend that inbound data is accessed via the one of the ‘Push’
services described above, the methods below describe how to retrieve all inbound message
data from Boomerang.
Elements of an inbound object
Element
Data
Type
Description
<InboundId>
<MobileNumber>
<InboundNumber>
<Text>
<Keyword>
Integer
String
String
String
String
<finRef>
<IsNew>
String
Boolean
<DateofInbound>
DateTime
The unique Id associated to the end user’s message
The end user’s (sender’s) mobile number
The number to which the end user’s message was sent
The content of the end user’s message
The keyword which is used as a unique for the inbound
number (where provided in the end user’s message as
this is optional)
Unique reference associated to the inbound number
Denotes whether the end user’s message has been
previously retrieved and marked as read
The date and time that the end user’s inbound message
was received
17-Feb-14
Page 34 of 46
 GetInbound
GetInbound
This operation retrieves all inbound data for a number (or keyword where specified). It is
mandatory to pass a number in the request whereas keywords are optional. Where the
number alone is passed all inbound data for that number will be retrieved. Where a number
is passed along with a keyword then only the data for that specific keyword will be retrieved.
This function will retrieve all inbound messages that have previously been marked as ‘read’
covering three months prior to the point at which the request is submitted and all ‘New’
(unread) responses covering two days prior to the point at which the request is submitted.
Parameter
/ Optional
username
M
password
M
licenseKey
M
inboundNumber
M
Keyword
O
New
O
markAsRead
O
adheres to the following format: XXXXX-XXXXX-XXXXX-XXXXXXXXXX-XXXXX. This is a case sensitive field.
The inbound number from which inbound message data is
retrieved which is assigned to the Boomerang account.
The keyword from which inbound message data is retrieved which
is assigned to the Boomerang account.
Will only return responses that have not previously been marked as
‘read’. To set this parameter pass ‘Yes’, ‘1’ or ‘True’.
Will mark all retrieved responses as ‘read’. To set this parameter
pass ‘Yes’, ‘1’ or ‘True’.
Please note that this method will not retrieve responses to outbound messages that have
been sent using threading. Responses to threaded messages are retrieved using the
‘GetResponse’ functions defined earlier in this document.
When polling the service for inbound message data, please limit these requests
to intervals of a least one minute.
11.5 Automated response messages
Each type of inbound identifier can be configured with a pre-defined automated response
which is returned to the end user initiating the MO message. The sender Id for this
automated response message is also customisable. Automated response messages are
configured by Boomerang when assigning the number to your account. Change requests
must be submitted by email to Boomerang at support@boomcomms.com.
17-Feb-14
Page 35 of 46
11.6 Provisioning inbound services
To request any of the inbound services described in this section, please contact your
Account Manager or Boomerang sales on +44 (0)20 7224 5555.
17-Feb-14
Page 36 of 46
12
Methods used to update the status of message data
The operations in this section enable the status of outbound, inbound and response
messages to be updated.
12.1 Methods used to mark data as read
These operations allow individual recipient responses and end user initiated inbound
messages to be flagged as ‘read’. These functions allow data to be flagged as ‘read’
retrospectively, where the ‘markAsRead’ parameter was not passed when first calling the
GetResponses or GetInbound functions.
 MarkResponseAsRead
 MarkInboundAsRead
MarkResponseAsRead
Marking a response or responses as ‘read’ allows a user to specify that only new (unread)
data is retrieved when making subsequent requests to the ‘GetResponse’ function.
Parameter
/ Optional
username
M
password
M
licenseKey
M
responseId
M
The Id for the response which is matched to the originating outbound
message. This is retrievable using the ‘GetResponses’ function.
MarkInboundAsRead
Marking an inbound message or multiple inbound messages as ‘read’ allows a user to
specify that only new (unread) data is retrieved when making subsequent requests to the
‘GetInbound’ function.
17-Feb-14
Page 37 of 46
Parameter
/ Optional
username
M
password
M
licenseKey
M
inboundId
M
The inbound Id which is associated to the inbound message. This
is retrievable via the ‘GetInbound’ function.
12.2 Methods used to close message transactions
Where a recipient response is longer required but the message remains active as the validity
expiration period has not been reached, the message can be manually closed. This could
be used where a specific System Virtual Number is required (using the preferredMobileNo
parameter). This section describes how to close active message transactions.
 CloseTicket
CloseTicket
This operation is used to close a message prior to validity expiration using the message Id
associated to the outbound message, which is automatically generated by Boomerang.
Parameter
Description
username
password
licenseKey
messageId
The Boomerang account username. This is unique for every account in the
system and is a mandatory, case sensitive field.
The Boomerang account password. A password must be at least 8 characters
in length and consist of at least one upper and lower case character and at
least one digit. This is a mandatory, case sensitive field.
A unique API key is automatically generated on creation of every Boomerang
account. Consisting of 35 characters, the API key adheres to the following
format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is also a
mandatory, case sensitive field.
The id of the original outbound message. This can be retrievable via the
‘GetMessage’ function.
17-Feb-14
Page 38 of 46
13
Methods used to query account status
For customers using a trial, demo or pre-paid service, this operation allows the available
message credit balance to be queried.
 NoOfCreditsAvailable
NoOfCreditsAvailable (Pre-paid, trial or demo accounts only)
Boomerang offers two types of customer account:



Trial accounts (provisioned automatically and free messages allocated)
Demo accounts (provisioned by Boomerang and free messages credits allocated)
Pre payment (messages purchased in advance)
Parameter
Description
username
password
licenseKey
The Boomerang account username. This is unique for every account in the
system and is a mandatory, case sensitive field.
The Boomerang account password. A password must be at least 8 characters
in length and consist of at least one upper and lower case character and at
least one digit. This is a mandatory, case sensitive field.
A unique API key is automatically generated on creation of every Boomerang
account. Consisting of 35 characters, the API key adheres to the following
format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is also a
mandatory, case sensitive field.
17-Feb-14
Page 39 of 46
14
Support
Service requests regarding service affecting issues are raised and monitored through our
Technical Support case management system. Such requests can be raised directly by the
customer or by the Technical Support Team on:
SUPPORT METHOD
CONTACT DETAILS
Ticket
Email
Telephone
http://ticket.boomcomms.com
technicalsupport@boomcomms.com
+44 (0)20 7224 3333

Customer originated requests: Any customer representative raising a ticket is
required to provide their name, e-mail address and a description of the request along
with the priority level pertaining to nature of the ticket being raised. Confirmation of the
service request, including a unique reference is sent to the e-mail address provided, with
status updates issued as action is undertaken.

Boomerang Support team request: Where service requests are raised verbally to the
Technical Support team, a ticket is raised by the team using the method described above
and confirmed to the nominated e-mail address also containing a unique ticket reference
which is quoted in all future correspondence that relates to the issue
17-Feb-14
Page 40 of 46
15
Appendix 1 – Message characteristics
15.1 GSM 03.38 Encoding
Languages using a Latin based alphabet (English, Spanish French etc) normally use GSM
03.38 encoded messaging as the standard configuration. GSM encoding allows up to 160
(7-bit) characters per single message and includes the most common accented forms,
certain special characters, and the Greek alphabet. A complete table of characters is
provided below:
Dec
Hex
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
0
1
2
3
4
5
6
7
8
9
A
B
C
D
E
F
0
0
@
£
$
¥
è
é
ù
ì
ò
Ç
LF
Ø
ø
CR
Å
å
16
10
Δ
_
Φ
Γ
Λ
Ω
Π
Ψ
Σ
Θ
Ξ
<ESC>
Æ
æ
É
32
20
SP
!
"
#
¤
%
&
'
(
)
*
+
,
.
/
48
30
0
1
2
3
4
5
6
7
8
9
:
;
<
=
>
?
64
40
¡
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
80
50
P
Q
R
S
T
U
V
W
X
Y
Z
Ä
Ö
Ñ
Ü
§
96
60
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
112
70
p
q
r
s
t
u
v
w
x
y
z
ä
ö
ñ
ü
à
NOTE: An escape character always precedes the characters {} \ ~ [ ] | €, which therefore
take two characters to send.
Multi-part or concatenated messages, containing more than 160 characters, are delivered as
a single SMS message. Each concatenated text message is limited to 153 characters rather
than 160 due to the need for user-data header (UDH) information. Mobile phones use UDH
information to enable them to link long messages together so that they appear as single
SMS messages in a recipient’s handset inbox.
An example of this is provided below:
Number of SMS
Number of characters in the linked message
1
2
160 characters
306 characters (2x153)
3
4
Etc
153 x Number of individual concatenated SMS messages
17-Feb-14
Page 41 of 46
15.2 Unicode messages (UTF-16 encoding)
Unicode messages use 16-bit character encoding rather than the standard GSM 03.38 encoded
characters listed above. This allows non-Latin based alphabets (Chinese, Arabic, Russian,
Mongolian etc) to be carried within the SMS. As the characters are 16-bit encoded (i.e require
more bits per character) a single SMS message is restricted to a maximum of 70 characters.
Multi-part or concatenated messages containing 16-bit encoded characters are delivered as a
single message but will be billed in 67 character segments. See below:
Number of SMS
1
2
3
4
Etc
Number of characters in the linked message
70 characters
67 x Number of individual concatenated SMS messages
15.3 Concatenated messaging restrictions
The quantity of characters allowed in a concatenated message and the successful delivery of it,
is dependent on the recipient’s network operator and the encoding of the characters within the
message. Concatenated messaging is well supported by the UK network operators where it is
possible to send messages containing in excess of 2000 GSM encoded characters. In the USA
however, successful delivery is usually restricted to a maximum of 3 three concatenated
messages (459 GSM encoded characters).
For specific destinations where concatenated messaging is required, please contact Boomerang
for more advice on availability and any restrictions.
17-Feb-14
Page 42 of 46
16
Appendix 2 – Error codes
Code
Message content
Message Description
400
‘Empty Message’
400
‘Invalid User’
400
‘Invalid IP’
400
‘Invalid number format’
400
400
‘No Mobile Numbers’
‘Too Many Mobile
Numbers’
No Email Addresses
Too Many Email
Addresses
‘No Telephone
Numbers’
‘Too Many Telephone
Numbers’
‘Not enough credits’
The message cannot be sent as there is no message content
provided with the request. Please ensure that the 'text'
parameter has been completed.
The credentials provided are not valid or the account is not
active
The IP address from which the requests originated is not
accepted by Boomerang
The mobile number provided is not formatted correctly and
contains too few or too many digits (less than 10 or more than
20)
There are no telephone numbers contained in the request
More than 50 telephone numbers were included in the request
400
400
400
400
400
500
501
‘Internal error’
Unsupported HTTP
method
There are no email addreses contained in the request
More than 50 email addresses were included in the request
There are no telephone numbers contained in the request
More than 50 telephone numbers were included in the request
There are insufficient message credits on the account (Trial
and Pre-paid customers only)
An internal within Boomerang occurred
An unsupported HTTP method is being used
17-Feb-14
Page 43 of 46
17
Appendix 3 – List of country codes
Name
Afghanistan
Albania
Algeria
Andorra
Angola
Anguilla
Antarctica
Argentina
Armenia
Aruba
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgium
Belize
Bermuda
Bhutan
Bolivia
Botswana
Brazil
Bulgaria
Burkina Faso
Burundi
Cambodia
Cameroon
Canada
Cayman Islands
Central African Republic
Chad
Chile
Christmas Island
Colombia
Comoros
Cook Islands
Costa Rica
Croatia
Cuba
Cyprus
Czech Republic
Denmark
Djibouti
Dominica
Dominican Republic
Ecuador
Egypt
El Salvador
Equatorial Guinea
Eritrea
Estonia
Ethiopia
Faroe Islands
Finland
France
French Polynesia
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Grenada
ISO
Code
AFG
ALB
DZA
AND
AGO
AIA
ATA
ARG
ARM
ABW
AUS
AUT
AZE
BHS
BHR
BGD
BRB
BLR
BEL
BLZ
BMU
BTN
BOL
BWA
BRA
BGR
BFA
BDI
KHM
CMR
CAN
CYM
CAF
TCD
CHL
CXR
COL
COM
COK
CRI
HRV
CUB
CYP
CZE
DNK
DJI
DMA
DOM
ECU
EGY
SLV
GNQ
ERI
EST
ETH
FRO
FIN
FRA
PYF
GMB
GEO
DEU
GHA
GIB
GRC
GRL
GRD
Prefix
Name
+93
+355
+213
+376
+244
+1264
+672
+54
+374
+297
+61
+43
+994
+1242
+973
+880
+1246
+375
+32
+501
+1441
+975
+591
+267
+55
+359
+226
+257
+855
+237
+1
+1345
+236
+235
+56
+618
+57
+269
+682
+506
+385
+53
+357
+420
+45
+253
+1767
+1809
+593
+20
+503
+240
+291
+372
+251
+298
+358
+33
+689
+220
+995
+49
+233
+350
+30
+299
+1473
Laos
Latvia
Lebanon
Lesotho
Liberia
Libya
Liechtenstein
Lithuania
Luxembourg
Madagascar
Malawi
Malaysia
Maldives
Malta
Marshall Islands
Martinique
Mauritania
Mauritius
Mexico
Moldova
Monaco
Mongolia
Montserrat
Morocco
Mozambique
Myanmar
Namibia
Nauru
Nepal
Netherlands
Netherlands Antilles
New Caledonia
New Zealand
Nicaragua
Niger
Nigeria
Niue Island
Norway
Pakistan
Palau
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Poland
Portugal
Puerto Rico
Qatar
Romania
Russia
San Marino
Saudi Arabia
Senegal
Sierra Leone
Singapore
Slovakia
Slovenia
Solomon Islands
South Africa
Spain
Sri Lanka
Sudan
Suriname
Swaziland
Sweden
Switzerland
17-Feb-14
ISO Code
Prefix
LAO
LVA
LBN
LSO
LBR
LBY
LIE
LTU
LUX
MDG
MWI
MYS
MDV
MLT
MHL
MTQ
MRT
MUS
MEX
MDA
MCO
MNG
MSR
MAR
MOZ
MMR
NAM
NRU
NPL
NLD
ANT
NCL
NZL
NIC
NER
NGA
NIU
NOR
PAK
PLW
PAN
PNG
PRY
PER
PHL
POL
PRT
PRI
QAT
ROU
RUS
SMR
SAU
SEN
SLE
SGP
SVK
SVN
SLB
ZAF
ESP
LKA
SDN
SUR
SWZ
SWE
CHE
+856
+371
+961
+266
+231
+218
+423
+370
+352
+261
+265
+60
+960
+356
+692
+596
+222
+230
+52
+373
+377
+976
+1664
+212
+258
+95
+264
+674
+977
+31
+599
+687
+64
+505
+227
+234
+683
+47
+92
+680
+507
+675
+595
+51
+63
+48
+351
+1787
+974
+40
+7
+378
+966
+221
+232
+65
+421
+386
+677
+27
+34
+94
+249
+597
+268
+46
+41
Page 44 of 46
Guadeloupe
Guam
Guatemala
Guinea
Guyana
Haiti
Honduras
Hong Kong
Hungary
Iceland
India
Indonesia
Iran
Iraq
Ireland
Israel
Italy
Jamaica
Japan
Jordan
Kenya
Kiribati
Kuwait
GLP
GUM
GTM
GIN
GUY
HTI
HND
HKG
HUN
ISL
IND
IDN
IRN
IRQ
IRL
ISR
ITA
JAM
JPN
JOR
KEN
KIR
KWT
+590
+1671
+502
+224
+592
+509
+504
+852
+36
+354
+91
+62
+98
+964
+353
+972
+39
+1876
+81
+962
+254
+686
+965
Syria
Taiwan
Tajikistan
Tanzania
Thailand
Tokelau
Tunisia
Turkey
Turkmenistan
Tuvalu
Uganda
Ukraine
United Kingdom
United States of America
Uruguay
Uzbekistan
Vanuatu
Vatican City
Venezuela
Vietnam
Yemen
Zambia
Zimbabwe
17-Feb-14
SYR
TWN
TJK
TZA
THA
TKL
TUN
TUR
TKM
TUV
UGA
UKR
GBR
USA
URY
UZB
VUT
VAC
VEN
VNM
YEM
ZMB
ZWE
+963
+886
+992
+255
+66
+690
+216
+90
+993
+688
+256
+380
+44
+1
+598
+998
+678
+39
+58
+84
+967
+260
+263
Page 45 of 46
18
No.
1
2
3
4
5
6
7
8
9
10
11
Appendix 4 - Summary of API methods
Method
NoOfCreditsAvailable
SendThreadedMessage
SendTextMessage
SendEmailMesage
SendVoiceMesage
GetMessage
GetResponses
GetInbound
MarkResponseAsRead
MarkInboundAsRead
CloseTicket
17-Feb-14
Page 46 of 46

Boomerang REST API Specification.

Transcription

Similar documents

The Boomerang from Obtazowa and its Prehistoric Context

USA ELAN Manual - Boomerang RC Jets

brochure

Reverse Telemarketing Campaign

Whitepages Pro Caller Identification API

APIs as a Foundation for Systems of Engagement

OMNITRAC LASER TRACKING SYSTEM

- Flight Toys

discount tickets - York County Regional Chamber of Commerce

What Makes Boomerangs Come Back?