Sep 25, 2015 - Email messages sent via the method 'SendEmailMessage' . ..... Delivering voice messages to numbers linked
SOAP API Specification & Integration Guide Boomerang r2.3.3 Author Document Version Date
Andy Allen 1.1 th 25 September 2015
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.
Contents 1 1 2 3 4 5
Context ...................................................................................................................................... 5 1.1 Boomerang – Intelligent Messaging ............................................................................. 5 Purpose ..................................................................................................................................... 5 Scope ......................................................................................................................................... 6 References ................................................................................................................................. 6 Definitions ................................................................................................................................. 6 Preparing for integration ........................................................................................................... 8 5.1 Connectivity settings .................................................................................................... 8 Proxy servers ................................................................................................................ 8 Email messages sent via the method ‘SendEmailMessage’ ......................................... 8 5.2
Account settings ........................................................................................................... 8
5.3
API Security .................................................................................................................. 8 API Key .......................................................................................................................... 9 Username and Password .............................................................................................. 9 Restrict access by IP address ........................................................................................ 9
5.4
Data security ................................................................................................................ 9
5.5
Messaging configuration settings ................................................................................. 9 SMS Messaging – Number management ................................................................... 10 Voice Messaging ......................................................................................................... 10
5.6 6
Workflow design ........................................................................................................ 11
Structure of the SOAP API ....................................................................................................... 12 6.1 Endpoints & service URL ............................................................................................ 12 6.2
Structure of Each Request .......................................................................................... 12 Example SOAP 1.1 Request ........................................................................................ 12 Example SOAP 1.2 Request ........................................................................................ 13
6.3 7
Error Handling ............................................................................................................ 13
Messaging solutions and communication channels ................................................................ 14 7.1 Overview of communication channels ....................................................................... 14 SMS Messaging ........................................................................................................... 14 Email Messaging ......................................................................................................... 14 Voice Messaging ......................................................................................................... 14 7.2
Messaging solutions ................................................................................................... 15 Intelligent 2-‐way messaging (SMS and Email) ............................................................ 15
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 2 of 55
Conversational / Chat messaging (SMS) ..................................................................... 15 Standard 2-‐way SMS messaging (SMS) ...................................................................... 15 1-‐way messaging (SMS) .............................................................................................. 15 Summary of messaging solutions with associated methods ...................................... 16 7.3
Message tickets .......................................................................................................... 16
7.4
Message ticket validity ............................................................................................... 17 Overview .................................................................................................................... 17 Rules associated to message ticket validity ............................................................... 17 Message validity with single and open tickets ........................................................... 17
8
API Functions used to send messages ..................................................................................... 18 8.1 Overview .................................................................................................................... 18 8.2
Elements of an outbound Message Object ................................................................ 18
8.3
Methods used to process SMS messages ................................................................... 19 Example Response ...................................................................................................... 19 Methods in this section .............................................................................................. 19 Destination specific requirements when sending SMS messages .............................. 23
8.4
Methods used to process Email messages ................................................................. 24 Methods in this section .............................................................................................. 24
8.5
Methods used to send voice messages ...................................................................... 25 Configuration options for voice messages ................................................................. 25 Response options for voice messages ........................................................................ 26 Delivering voice messages to numbers linked to automated systems ....................... 26 Methods in this section .............................................................................................. 26
9
Status notifications for each messaging channel .................................................................... 28 9.1 Overview of status notifications for SMS ................................................................... 28 9.2
Overview of status notifications for email messages ................................................. 29
9.3
Overview of status notifications for voice messages ................................................. 29 Retrying delivery of voice messages .......................................................................... 29
9.4 10
Push notifications for delivery status updates ........................................................... 29
Methods used to query message data .................................................................................... 31 10.1 Elements of an outbound Message Object ................................................................ 31 10.2
Methods used to query outbound message data ...................................................... 31 GET Operations .......................................................................................................... 32
10.3
methods used to query Recipient responses ............................................................. 33
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 3 of 55
Elements of a response object ................................................................................... 33 Example SOAP Response ............................................................................................ 34 Get New Responses .................................................................................................... 34 Get All Responses (including previously marked as ‘read’) ........................................ 36 10.4
Retrieving responses via ‘Push’ .................................................................................. 38 Push to a URL ............................................................................................................. 38 Methods is this section .............................................................................................. 38 Push to email .............................................................................................................. 40
11
Fixed inbound communications .............................................................................................. 41 11.1 Overview .................................................................................................................... 41 11.2
Summary of inbound communication addresses ....................................................... 41
11.3
Methods used to retrieve mobile originated messages ............................................. 41 Elements of an inbound object .................................................................................. 41 Methods in this section .............................................................................................. 42
11.4
Retrieving mobile originated messages by ‘Push’ ...................................................... 43 Push to a URL ............................................................................................................. 43 Retry process for push service ................................................................................... 44 Push to email address ................................................................................................ 44
12
11.5
Automated response messages ................................................................................. 44
11.6
Provisioning inbound services .................................................................................... 44
Methods used to update message transactions ..................................................................... 45 12.1 Methods used to mark data as read .......................................................................... 45 Methods in this section .............................................................................................. 45 12.2
Methods used to close message transactions ............................................................ 46 Methods in this section .............................................................................................. 46
13
Methods used to query service account settings .................................................................... 47 Methods in this section .............................................................................................. 47
14 15
Support .................................................................................................................................... 48 Appendix 1 – SMS messaging technologies and character encoding ...................................... 49 15.1 GSM 03.38 Encoding .................................................................................................. 49
16 17 18
15.2
Unicode messages (UTF-‐16 encoding) ....................................................................... 50
15.3
Concatenated messaging restrictions ........................................................................ 50
Appendix 2 – Error codes ........................................................................................................ 51 Appendix 3 – List of country codes ......................................................................................... 53 Appendix 4 -‐ Summary of API methods ................................................................................... 55
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 4 of 55
1 Context 1.1 Boomerang – Intelligent Messaging Boomerang is a unique patented service that enables any mobile device to be integrated into automated business processes globally, using Intelligent 2-way communications. 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.
1 Purpose This document is intended to assist developers who wish to use the Boomerang HTTPS SOAP API to implement one-way, two-way and/or Intelligent 2-way 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
The document is divided into three core sections: • Preparing for integration – This section defines the pre-requisites for a successful integration • Structure of the SOAP API • An introduction to the available messaging solutions • The various programming methods and commands available when using the API for to send messages across each communication channel (SMS, email and voice) • The various programming methods and commands available when using the API for to retrieve outbound message data and response data • Using Boomerang to manage end user initiated communications
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 5 of 55
• The various programming methods and commands available when using the API to update active message transactions and account settings • Support – This section describes the process for raising support queries.
2 Scope This document is intended for technical architects and designers who are implementing the Boomerang services on behalf of an organisation and 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 RESTful methodology should refer to the document ‘RESTful API Specification & Integration Guide BR211’.
3 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.
4 Definitions NAME API/License Key Auto-reply message Boomlocal Customer Delivery status Dynamic header Recipient
Fixed Inbound Number (FIN)
Keyword Exclusive number(s) SMTP System Virtual number (SVN)
SHORT DESCRIPTION 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 guaranteeing that SMS are sent from a number that is local to the Recipient's destination. 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 originating 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 account used to receive inbound communication initiated by a Recipient or responses to 2-way broadcast communication, which has been initiated from the inbound number. Where a Fixed Inbound Number is used as an originating 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 an originating 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 an originating ID for Intelligent 2-way SMS. This number also
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 6 of 55
Message validity period Open ticket Partner Password Recipient Threading Username
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 originating Id. A registered Boomerang partner utilising the Boomerang API for message delivery. Unique alphanumeric string consisting of at least 8 characters used to validate an API request that is created on registration of a Boomerang account. MSISDN receiving a mobile terminated (MT) message from Boomerang The process of matching responses to originating outbound messages, regardless of quantity or sequence used within Intelligent 2-way messaging Unique value used to validate an API request that is created on registration of a Boomerang account.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 7 of 55
5 Preparing for integration Before using this guide we recommend that you have addressed the following:
5.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 the method ‘SendEmailMessage’ Email messages are sent using the domain @api.boomerangicomms.com. It is therefore important to ensure that traffic from this domain is permitted access into the local environment.
5.2 Account settings Before an application or service can send and receive messages, a Boomerang service account is required. On creation of the service account, the API key is automatically generated along with a username and password (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.
5.3 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 8 of 55
Requests submitted to the API are subject to the following authentication requirements: 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-R65C4- SFA42-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. A service account username and password are passed as mandatory parameters within each API function. Restrict access by IP address All requests can be authenticated according to an IP address. Where an IP address is provided, Boomerang will only process requests from specific IP address. All requests to apply this security feature should be submitted to
[email protected].
5.4 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 configure any or all of the options below: • Null digits: An optional feature used to overwrite the digits in a Recipient's mobile number, ensuring that the number is not accessible anywhere in Boomerang’s systems. It is possible to choose to leave the first three, last three or both the first and last three digits in the number visible, to assist with issue de-bugging. • Null content: An optional feature used to overwrite the content of an outbound message and any associated response(s);; ensuring it is not accessible anywhere in Boomerang’s systems. • Null period: A feature used to set the period after which the Null Digits and Null content features are applied to message transactions. This may be set to overwrite immediately after processing or after a pre-defined number of days.
5.5 Messaging configuration settings Boomerang provides several messaging configuration options relating to the available messaging channels. These are described below: The following configuration options apply to all communication channels unless highlighted:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 9 of 55
• Replace non-GSM encoded characters: An optional feature that is used to convert any Unicode encoded characters passed in the content of an outbound message, to an equivalent GSM encoded character. Where no equivalent GSM encoded character is identified it may not be possible to convert a Unicode character and the message would be sent as a Unicode message. • Message validity*: The period over which a message will remain ‘active’ allowing Recipient responses to be automatically matched to active outbound messages. Upon a message reaching its associated validity limit, it will close and any responses returned after this period are not matched to the originating message. The default validity period is set to 24 hours and any change to the validity subscription must be submitted in writing to Boomerang. *Not applicable to voice messaging as responses are not ‘threaded’
SMS Messaging – Number management • Home country numbers: A mandatory configuration that determines the locality of the range of System Virtual Numbers that will be used as the originating Id for all outbound messages. The default number range will be set to use UK virtual numbers, unless otherwise specified during the on-boarding process. The ‘Home’ country must be set to a country where Boomerang has local numbers available. • Boomlocal feature: An optional feature that allows messages to be sent using a System Virtual Number local to the destination of the Recipient as the originating Id for a message. Where a number range has additional countries associated to it (this configuration would be set by Boomerang), messages sent to destination numbers that match those associated countries are also delivered using a number from that range as the originating Id. Voice Messaging • Welcome content: Customer defined content that is delivered to the Recipient immediately after answering a voice message call. The welcome content is customisable for each individual service and applies to all messages processed through that account. This content is usually defined during the on-boarding process. • Re-direct content: Customer defined content that is played to any Recipient selecting the call re-direct option 9 (as a keystroke from the device). This allows the call to be diverted to a pre-defined contact number. The re-direct content is customisable for each individual service account and applies to all messages processed through that account. This content is usually defined during the on- boarding process. • Re-direct number: A customer defined number used in the process described above (Re-direct content) • Exit content: Customer defined content that is played to a Recipient at the end of a voice call. The exit message content is customisable for each individual service account and applies to all messages processed through that account.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 10 of 55
• Retry schedule: Voice messages that fail to receive an acknowledgement from the Recipient on the first attempt may be retried. The parameters for retry schedule may be determined by a customer with the ability to set both the number of attempted retries and the duration between each.
5.6 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’ describes the core functionality of Boomerang API, which will provide assistance when designing workflow. If you have not already received this document it is available on request by contacting
[email protected]. This API specification provides a description of the methods available that can be used during composition of workflow.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 11 of 55
6 Structure of the SOAP API SOAP is a protocol for exchanging XML-based messages using HTTP/HTTPS. It uses XML as its message format and is transmitted via HTTP/S. SOAP messages are in the form of a packet and submitted to a SOAP portal for our gateway to pass on The Boomerang API itself exposes a large number of methods, which return structured responses, making it as convenient as possible for developers to build highly usable client applications on top of the Boomerang service. It is intended for software developers who are familiar with technologies such as HTML, JavaScript, Perl, .NET, PHP, and web services
6.1 Endpoints & service URL The API endpoint adheres to the following structure: https://api.boomerangicomms.com/soap/{SOAP service}.php “Service” denotes the version of the service, either SOAP 1.1 or SOAP 1.2. All communication via the API is SSL encrypted over HTTPS (128 or 256 bit). Any non-secure requests are automatically rejected. To support as many programming languages as possible, the API operates both SOAP 1.1 and SOAP 1.2. The location of the WSDL is different depending on which version of the service you wish to integrate with (SOAP1.1 or SOAP 1.2). Below is the current location of each WSDL: SOAP 1.1 endpoint: https://api.boomerangicomms.com/soap/soap11.php?wsdl SOAP 1.2 endpoint: https://api.boomerangicomms.com/soap/soap12.php?wsdl Submit your SOAP requests via HTTP or HTTPS to the following URL: https://api.boomerangicomms.com/soap/soap12.php .Net developers should ensure that the connection URL doesn't contain ‘?wsdl’ at the end of the URL.
6.2 Structure of Each Request SOAP requests are “envelopes” of specially formatted XML data posted to a URL. To find out more about SOAP please visit: http://www.w3.org/TR/soap/. Depending on which SOAP service version is used the SOAP server endpoint URL will either point to either of the endpoints listed above. Below is an example request to the “GetMessageById” operator in both SOAP 1.1 and SOAP 1.2. Example SOAP 1.1 Request https://api.boomerangicomms.com/soap/so ap11.php https://api.boomerangicomms.com/SoapSe
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 12 of 55
rviceContract/GetMessageById MY USERNAME MY PASSWORD XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX xxxxxx
Example SOAP 1.2 Request https://api.boomerangicomms/soap12.php https://api.boomerangicomms.com/SoapServiceContract/GetMessageById MY USERNAME MY PASSWORD XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX xxxxxx
6.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. In addition the message will be translated into various national languages. The language used for the error response will be provided in the request URL. If the language cannot be determined (because it was either not present in the URL or not supported by the system) the error response will be in English. Developers should rely on the code to detect and manage errors because the message may change over time. For a full list of error codes and their corresponding messages, please go to Appendix 2.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 13 of 55
7 Messaging solutions and communication channels 7.1 Overview of communication channels Boomerang’s messaging platform provides Omni-channel messaging via SMS, email and voice. The table below defines the messaging solutions (described in the section above) supported across each communication channel.
Intelligent 2-way
Conversational
2-way broadvast
1-way broadcast
SMS
Email
Voice
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 and load balance across 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:
Boomerang is embedded in CRM workflow!
Mobile Aggregator!
Mobile Operator!
Figure 1 - Infrastructure for SMS delivery
Email Messaging Boomerang uses Simple Mail Transfer Protocol (SMTP) to transmit email messages over the Internet. Our clustered and fault tolerant VmWare Cloud provides geographical redundancy for all inbound SMTP traffic between two split locations, Manchester and London (UK). 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 global delivery of voice messages to both fixed line and mobile telephone numbers. Through the use of multiple upstream partners we can dynamically route between and load balance across voice carriers to optimise the quality of service delivery. In turn,
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 14 of 55
each of our voice carriers has multiple routes in place, allowing them to reach almost all operators globally.
7.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: Intelligent 2-way messaging (SMS and Email) Intelligent 2-way (or ‘threaded’) messaging is at the core of Boomerang’s (patented) functionality and enables multiple concurrent outbound messages to be matched with their associated responses, irrespective of quantity and order. This matching process allows responses to be used to automate subsequent activities. Threading SMS Messages This process uses the ‘SendTextMessage’ function. When called, a Boomerang System Virtual Number (SVN) is automatically selected as the sender Id for a message;; each message is sent using SVN’s owned by Boomerang and a Recipient can respond to each message independently. Threading Email Messages This process uses the function SendEmailMessage and creates a unique email address based on the message Id for the transaction, allowing email responses to be matched back to the originating transaction. Conversational / Chat messaging (SMS) Boomerang allows a service or application to engage in an SMS ‘conversation’ with a Recipient using a preferred number, allowing the same SVN to be used as the sender Id for all messages relating to the same theme or conversation. This will ensure consistency within the Recipient’s device, as messages relating to a specific ‘conversation’ will arrive from the same number and will be displayed chronologically. This allows multiple simultaneous conversations to be managed within a single device, each bound by a unique SVN. Standard 2-way SMS messaging (SMS) Unlike ‘threading’, Standard 2-way messaging does not match a Recipient’s response to the originating message and would therefore be used for campaigns (with a fixed inbound number) where responses are collated, but are not used to automate subsequent activities. The ‘originatingMobileNo’ parameter of the ‘SendTextMessage’ allows a bespoke number to be passed as the sender Id for a message and where a Fixed Inbound Number is used, responses are stored in the Boomerang solution and can be retrieved via the API or pushed to a URL. As responses are not tracked against the outbound messages there no validity period associated to a standard 2-way message. 1-way messaging (SMS) When a message is sent using a Dynamic Header rather than a System Virtual Number as the originating Id, a user configurable alphanumeric code, (e.g. company name) is displayed in the handset inbox. This communication type requires the parameter ‘dynamicHeader’ to
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 15 of 55
be passed within the method ‘sendTextMessageWithDynamicHeader’. A Recipient cannot respond to a message sent using a Dynamic Header and as such there is no validity period associated to a 1-way message. The image below details the typical message flow associated with each of the methods for sending and receiving messages:
Figure 2 - Boomerang messaging solutions
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)
STM
STMWPN
SEM
SVM
Conversational messaging (Preferred No.)
Intelligent 2-way messaging
Simple 2-way messaging (Originating No.)
The parameter required within each method is stated in brackets. Key to methods in table above: • STM = SendTextMessage • STMWPN = SendTextMessageWithPreferredNumber • SEM = Send Email Message • SVM = Send Voice Message
7.3 Message tickets Boomerang provides the capability to issue two different types of ticket for Intelligent 2-way messaging, defined below:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 16 of 55
• Single ticket: The default selection for all Intelligent 2-way messages. A single ticket / message is automatically closed on receipt of the single response message. • Open ticket: An optional feature applicable that allows an end user to return multiple response messages to the same outbound message request. This option is selected using a parameter within the SendTextMessage function.
7.4 Message ticket validity Overview All ‘Intelligent 2-way’ messages sent through Boomerang 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. A default validity period of 24 hours is allocated to a service account and additional message validity may be selected on purchasing Boomerang services. The subscription selections are as follows: 48 hours, 96 hours, 1 week, 2 weeks, 1 month or 2 months Rules associated to message ticket validity When processing message requests, please consider the following: • 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. 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 • 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 when reaching its expiry – whichever occurs first. Single tickets can be closed manually, prior to a Recipient’s response, using the CloseTicket function. An open ticket will close on expiry of the validity period or if closed manually using the CloseTicket function.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 17 of 55
8 API Functions used to send messages 8.1 Overview The objective of this specification document is to define all of the functions contained in the SOAP API and assist the user in selecting the methods that are most appropriate to the type of service to be implemented. This section contains all of the specific functions required to send messages via the SOAP API. A description is provided for each method along with a table describing the available the parameters and the required structure for each parameter value.
8.2 Elements of an outbound Message Object The elements of an outbound Message Object relating to all send functions are listed in the table below: Element
Data Format
MessageId CustomIdentifier
Integer String
CampaignName
String
From
String
Destination
String
Text
String
ValidityPeriod
String
IsOpenTicket
Boolean
ConversationId
String
EmailReplyTo
String
Source
String
DateCreated
DateTime
Status
String
Description The transaction id for the message generated by Boomerang. Bespoke message identifier chosen by the customer. Optional Identifier which can be used to group messages into specific campaigns Boomerang virtual number, dynamic header or bespoke number used as the originating Id for a message. The Recipient’s mobile phone number. The parameter 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) The content of the message to be sent to the Recipient. Messages containing 160 characters or less are delivered and billed as a single message. Concatenated messages contain more than 160 characters message are also delivered as a single message but will be billed in multiples of 153 characters*. Please refer to Appendix 1 for further information regarding message characteristics and supported character sets. 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. 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. 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. The 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 status associated to a message. Delivery status notifications for SMS messages are described earlier
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 18 of 55
8.3 Methods used to process SMS messages The methods described in this section enable customers to perform 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. 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 ‘customIdentifier’ parameter. Example Response This example illustrates the structure of an SOAP response containing Message Objects. using SOAP 1.1 on server api.boomerangicomms.com returned the result of stdClass Object ( [GetMessageByIdResult] => stdClass Object ( [MessageId] => 2339363 [CustomIdentifier] => my ID [CampaignName] => My Campaign [From] => +447860001000 [MobileNo] => +447836123456 [Text] => Network test [ValidityPeriod] => 24 Hours [IsOpenTicket] => [PID] => [EmailReplyTo] =>
[email protected] [Source] => Origin [DateCreated] => 2013-02-14T07:25:43 [Status] => Sent ) ) and it took 0.067574977874756 seconds
Methods in this section POST Operations
• • • •
sendTextMessage sendTextMessageWithDynamicHeader sendTextMessageWithCustomNumber sendTextMessageWithPreferredNumber
sendTextMessage
This is the core function used to ‘thread’ SMS messages. Threading is the process that matches outbound messages with their responses and uses System 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 SMS message. The structure of the method is as follows: sendTextMessage {username, password, licenseKey, campaignName, conversationId, customIdentifier, RecipientsMobileNo, textMessage, autoResponseMessage, validityPeriod, isOpenTicket, emailResponsesTo, source}. Below is a description of each parameter available with this method: Parameter Description username password
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
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 19 of 55
licenseKey campaignName conversationId customIdentifier
RecipientsMobileNo
textMessage
autoResponseMessage
validityPeriod
isOpenTicket emailResponsesTo Source
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. Optional Identifier, which can be used to group messages into campaigns. 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. 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) 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. 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]. The maximum validity that may be passed is determined by the period set on the customer’s service account. 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. 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.
sendTextMessageWithDynamicHeader
This operation is used for 1-way (dynamic header) messaging. This function will send an SMS message to a Recipient using an alphanumeric dynamic header as the originating Id. A dynamic header must contain a maximum of 11 characters avoiding use of non-GSM encoded characters such as spaces or underscores. A Recipient cannot respond to a message sent using dynamic header. The structure of the method is as follows: sendTextMessageWithDynamicHeader {username, password, licenseKey, campaignName, conversationId, customIdentifier, dynamicHeader, RecipientsMobileNo, textMessage, source} Below is a description of each parameter available with this method:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 20 of 55
Parameter username password
licenseKey campaignName customIdentifier
dynamicHeader
RecipientsMobileNo
textMessage
source
Description 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. Optional Identifier, which can be used to group messages into 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. An alpha numeric originating ID for each message. This can be 11 characters or less in length and is a mandatory field. A dynamic header does not accept spaces. 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) 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 allowing the customer to enter the originating application for the message.
sendTextMessageWithCustomNumber
This operation is primarily used for standard 2-way broadcast messaging and will send an SMS message to a Recipient, using a bespoke number (e.g. a fixed inbound number or a user’s own mobile number for example). Where a fixed inbound number is used as the message originator, responses are stored in the Boomerang solution and can be retrieved via the API (using the methods getInboundMessages or getAllNewInboundMessages). However, as these responses are not tracked against the original outbound message, there is no validity period associated to messages sent using this function. Any requests that are passed using a number that has not been provided by Boomerang are not stored in the Boomerang solution and cannot be retrieved via the API. The structure of the method is as follows: sendTextMessageWithCustomNumber {username, password, licenseKey, campaignName, customIdentifier, originatingMobileNo, RecipientsMobileNo, textMessage, source} Below is a description of each parameter available with this method: Parameter Description username password
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
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 21 of 55
licenseKey
campaignName customIdentifier originatingMobileNo RecipientsMobileNo
textMessage
source
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. Optional Identifier, which can be used to group messages into 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. A bespoke number that is used as the originating ID for a message. Any response will be returned to the number passed. This is a mandatory field. 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) 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 allowing the customer to enter the originating application for the message.
sendTextMessageWithPreferredNumber
This parameter allows a specific virtual number (selected by the customer) to be used as the originating Id for a message (in preference to a System Virtual Number selected by Boomerang). This method would be used to update a specific ‘conversation’ thread on the recipient’s device by aligning the SVN to that conversation. As smart-phone deivces display the chronology of SMS messages a according to the originating name or number this is especially important where multiple concurrent ‘conversations’ are taking place with the same recipient. Consequently, a recipient can quickly identify messages relating to a 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) to maintain the integrity of message threading.
The structure of the method is as follows: sendTextMessageWithPreferredNumber {username, password, licenseKey, preferredMobileNo, campaignName, conversationId, customIdentifier, RecipientsMobileNo, textMessage, autoResponseMessage, validityPeriod, isOpenTicket, emailResponsesTo, source}. Below is a description of each parameter available with this method: 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
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 22 of 55
preferredMobileNumber
campaignName conversationId customIdentifier
RecipientsMobileNo
textMessage
autoResponseMessage
validityPeriod
isOpenTicket emailResponsesTo Source
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. A Boomerang virtual number that is passed by the customer and is used as the originating ID for a message in place of a number automatically selected by Boomerang. Any response will be returned to the number passed. This is a mandatory field. 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. Optional Identifier, which can be used to group messages into specific campaigns. 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. 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) 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. 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 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. 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.
Destination specific requirements when sending SMS messages Please note that delivery requirements may vary according the specific destination in which the Recipient is located. For example, some destinations will only permit messages sent with an alphanumeric dynamic header, whilst others require a numeric only originator (SVN). Additional destinations may only permit messages that arrive from a numeric originator that is local to the destination. As such, not all of the methods described in this section are applicable when attempting to reach certain destinations. For more information regarding destination specific requirements, please contact Boomerang on
[email protected]
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 23 of 55
8.4 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 and parameters are case sensitive. 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 ‘customIdentifier’ parameter.
Methods in this section • sendEmailMessage sendEmailMessage
This function can be used to thread email dialogue between an application and email Recipient. Email messages are always sent from an address that is generated automatically by Boomerang, when processing the request. The email address used adheres to the following structure: and ensures that all responses are matched to the relevant outbound email message. Using the ‘emailFrom’ 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. The structure of the method is as follows: sendEmailMessage {username, password, licenseKey, RecipientsEmail, emailFrom, emailSubject, campaignName, conversationId, customIdentifier, textMessage, autoResponseMessage, validityPeriod, isOpenTicket, emailResponsesTo, source}. Below is a description of each parameter available with this method: Parameter Description username password
licenseKey RecipientsEmail emailFrom emailSubject campaignName
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 Recipient’s email address The originating Id displayed in the Recipient’s email inbox. Where a value is not passed, ‘he originating email address is used as the default The subject of the email displayed in the Recipient’s email inbox. Where a value is not passed, ‘Email from Boomerang’ is used as the default subject Optional Identifier, which can be used to group messages into specific
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 24 of 55
conversationId customIdentifier textMessage autoResponseMessage
validityPeriod
isOpenTicket emailResponsesTo Source
campaigns. 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. 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 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 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. 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.
It is important to ensure that there are no restrictions in place that 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 network or client level spam filters.
8.5 Methods used to send voice messages The message content passed within a voice request is relayed to the Recipient by an IVR service. 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. Customers wishing to track messages using an identifier generated by their own application, a bespoke reference may be passed within the ‘customIdentifier’ parameter. Recipients can respond to messages using keystrokes on their telephone keypad and as this information is returned back to the Boomerang platform, it can be retrieved across the API using the ‘GetResponse’ methods described later in this document. Configuration options for voice messages As described earlier in this document, customers using voice messaging may pre-configure settings for each service account. The options are defined below: Intro message: Optional field containing content that is played to the Recipient immediately on answering a voice message. When configuring the intro message it is possible to provide two keystroke selections - option 1 to allow the Recipient to listen to the message or option 2 to allow the Recipient to decline the request. Intro message content
Keystroke
Keystroke Action
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 25 of 55
Customer defined
options 1 2
Proceeds to main message content Terminates the voice call
Re-direct number: A feature allowing the voice call to be re-directed to a different number Re-direct content: The content of the message played to the Recipient when the call is re- directed to the re-direct number Re-direct message content Keystroke options Customer defined
9
Keystroke Action Re-directs the voice call to the re-direct number provided
Exit message: Optional field containing content that is played to the Recipient after listening to the message or completing any actions requested in the main message. The settings are configured during the on-boarding process for each Boomerang service account requiring voice communications. Response options for voice messages All responses to voice message calls are returned via a keystroke from the Recipient’s mobile device. As defined in the table below, when configuring an outbound voice message that requires a response, any keystroke option between one and nine can be made available to select for the recipient to select from Response content
Keystroke Keystroke Action options Any number Returns the keystroke value as a response between 1 associated to the originating message and 8
Determined by keystroke response to originating message It is not possible to make a telephone call to a system virtual number, as these numbers are only active for data. Although it possible to send an SMS message to a system virtual number, this response will not be matched to the original outbound voice message and the user will therefore be unable to access any such responses. Delivering voice messages to numbers linked to automated systems Messages delivered to a number that is associated to an automated system such as a switchboard or IVR system, are considered answered but will not reach the intended Recipient. As an automated service would be unable to forward any voice calls, it is recommended that customers only use direct dial numbers.
Methods in this section The methods described in this section enable delivery of single or batched voice message requests. A valid licence key, username and a password must be provided with all requests. All parameters are case sensitive. • SendVoiceMessage
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 26 of 55
SendVoiceMessage
This function is used to send 2-way voice messages 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. Responses to voice messages are returned via a keystroke selected via the device keypad. sendVoiceMessage: {username, password, licenseKey, campaignName, customIdentifier, conversationId, RecipientsmobileNo, textMessage, validityPeriod, emailResponsesTo, source}. Below is a description of each parameter available with this method: Mandatory / Parameter Description Optional username
M
password
M
licenseKey
M
campaignName
O
customIdentifier
O
conversationId
O
RecipientsMobileNo
M
textMessage
M
validityPeriod
M
emailResponsesTo
O
Source
O
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- XXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory, case sensitive field. Optional Identifier that can be used to group messages by specific campaigns. A value generated by the customer’s application that can be associated to a single message or to multiple messages. If this is not required pass null or an empty value. 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. The Recipient’s destination number that 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. 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 in segments of 153 characters. Please refer to Appendix 1 for further information regarding message characteristics and supported character sets. A mandatory field that 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] The email address to which a Recipient’s response will be forwarded. The originating application for the message.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 27 of 55
9 Status notifications for each messaging channel The API provides the ability for outbound message data to be retrieved. Along with all key information relating to the transaction, this also provides access to an associated delivery state. The status notifications for each communication channel are defined in this section.
9.1 Overview of status notifications 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 no further status notification has been received This could be due to, for example: o The Recipient’s handset being switched off at the time delivery was initially attempted o The Recipient’s handset not being registered on the network the time delivery was initially attempted. o The Recipient’s network operator 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: Not all network operators in some destinations support delivery notifications (notably USA and Canada);; 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 network operator could not reach the Recipient’s handset. This could be due to: o The Recipient’s handset inbox is full o The mobile number is disconnected o The network operator has blocked the inbound message service. • 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 28 of 55
9.2 Overview of status notifications for email messages Boomerang classifies the status of email messages according to the following: • Sent: The message has been processed by Boomerang has not been received at the Recipient’s mail server • Delivered: The message has been delivered to the Recipient’s inbox (based on Recipient’s reply to the originating message) • Queued: The message has been processed and is queued at the Recipient’s mail server • Rejected: The message was rejected by the Recipient’s mail server (e.g. the mailbox does not exist) • Pending: The message currently resides on the Boomerang mail server pending re- submission;; this is due to the Recipient’s mail server being unavailable when the first request was submitted. The retry is implemented as follows: o 1st – 5 mins o 2nd – 1 hour o 3rd – 24 hours o 4th – 48 hours (If unsuccessful status updated to ‘Rejected’)
9.3 Overview of status notifications for voice messages Boomerang classifies the status of voice messages according to the following: • Delivered: The Recipient has confirmed receipt of the message via the keystroke entry ‘1’ after listening to the welcome message or has made a keystroke response against the main message • Accepted: The Recipient has confirmed acceptance to listen to the message (selecting option ‘1’ to the welcome message) but hung the call during the main message • Ignored: The Recipient has either rejected the call via their device or failed to answer the call • Rejected: The Recipient makes the keystroke response ‘2’ to the welcome message • Failed: The message could not be delivered as the Recipient’s device could not be reached by the carrier • Hung: The Recipient ends the call during the welcome message without making a keystroke response • Expired: The message could not delivered within the retry period applied by at the Service Account level Retrying delivery of voice messages The status notifications ‘Ignored’ and ‘Hung’ will trigger a retry (providing that a retry policy has been configured against the customer’s service account).
9.4 Push notifications for delivery status updates It is possible to access a delivery status notification update from the upstream carrier by providing a URL to which Boomerang will push this data. The URL provided must be
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 29 of 55
actively available and any potential restrictions preventing Boomerang’s messaging platform from reaching the customer’s platform should be addressed (e.g. firewalls). The notification is structured as an HTTP GET and the following variables are included: • messageId – The unique transaction Id assigned by Boomerang • status – The updated status of the message • statusTime – The time that the status was last updated A structured example is provided below: messageId => 7244 status => D statusTime => 2015-09-25
Please note that the default status of a message is set to ‘Sent’, any push notifications will be triggered when an updated status notification is received into Boomerang platform from the upstream supplier. The required URL is manually configured by Boomerang on receipt of a written request. All written requests should be submitted to
[email protected]
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 30 of 55
10 Methods used to query message data An outbound message is a message that 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 an outbound message transaction. Element
Data Format
Integer String
String
String
String
String
String
Boolean
String
String
String
DateTime
String
Element
Data Format
Description The transaction id for the message generated by Boomerang. Bespoke message identifier chosen by the customer. Optional Identifier which can be used to group messages into specific campaigns Boomerang virtual number, dynamic header or bespoke number used as the originating Id for a message. 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) The content of the message to be sent to the Recipient. Messages containing 160 characters or less are delivered and billed as a single message. Concatenated messages contain more than 160 characters message are also delivered as a single message but will be billed in multiples of 153 characters. 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. 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. 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. The 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 status associated to a message. Delivery status notifications for SMS messages are described earlier Description
10.2 Methods used to query outbound message data The method listed in this section provides the ability to retrieve data relating outbound SMS message transactions.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 31 of 55
GET Operations When calling the method in this section using the method name as presented below, the response data will be retrieved in SOAP. • getMessageById getMessageById
This operation will retrieve all of the information associated to a single message transaction 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 message Id must be provided when retrieving message data and the Id must relate to a message that was sent no longer than 12 months prior to the date that the request is submitted. The structure of the method is as follows: getMessageById {username, password, licenseKey, messageId} Parameter username password
licenseKey messageId
Description 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 message generated by Boomerang. This is a mandatory field.
An example response is presented below: using SOAP 1.2 on server api.boomerangicomms.com
returned the result of
stdClass Object ( [GetMessageByIdResult] => stdClass Object ( [MessageId] => 2438758
[CustomIdentifier] => GetMessageById [CampaignName] => GetMessageById [From] =>
+447860001002 [MobileNo] => +447836000999 [Text] => GetMessageById [ValidityPeriod]
=> 24 hours [IsOpenTicket] => [PID] => [EmailReplyTo] =>
[email protected] [Source] => GetMessageById [DateCreated] => 2013-03-14T07:25:50 [Status] => Delivered ) )
and it took 0.062051057815552 seconds
Using the message delivery status The response returned includes the delivery status of a message (). 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. Please refer to the section ‘Overview of message delivery states’ for a definition of each delivery status.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 32 of 55
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. getLatestDRs This method is used to manage the bulk retrieval of delivery status notifications relating to outbound message sent via Boomerang. The section ‘Overview of message delivery states’ provides a breakdown of the possible statuses that may be returned. A single request returns multiple delivery status notifications, based on any of the following: • A specified quantity of minutes • A start and end date / time • A start and end record Id
10.3 methods used to query Recipient responses A response is a direct reply to an Intelligent 2-way message originating from the Boomerang service. Boomerang’s ability to process Recipient responses is governed by the following: • The originating Id used for a message – A response cannot be retrieved if the original message was sent with a dynamic header or with a custom number • The ticket ‘type’ – 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 • Whether the original message was sent with the ‘Open Ticket’ feature then the Recipient will be able to send multiple replies • Whether the validity period of the message has expired Boomerang will be unable to match the Recipient’s response with a message ticket It is possible to retrieve data using different elements of a response object via individual methods and within each, an option is provided that allows any retrieved data to all be flagged as ‘read’ so that same data will not be retrieve as part of future requests. The methods described in this section are will allow responses to outbound SMS messages to be retrieved. The methods are separated between getAllNew functions (responses have never been retrieved previously) and getAll functions (new responses along with responses that have already been retrieved). With every request a valid license key, username and a password must be provided. All parameters are case sensitive and are considered mandatory unless otherwise stated. Elements of a response object Data Element Type
Integer
Integer
String
Description The unique Id for the Recipient’s response. The message Id for the original outbound message, which is automatically returned by Boomerang. The custom identifier provided with the original outbound message.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 33 of 55
String
String
String String Boolean
DateTime
DateTime
The Recipient’s full name (where provided)* The Recipient’s telephone number or email address (where email comms used) This is a Boomerang number or short code. The content of the Recipient’s response. Denotes an unread message. The date and time that the Recipient received the message. The date and time that the Recipient’s response was received by Boomerang.
*The ability to add Recipient data is not currently available
Example SOAP Response This example illustrates the structure of an SOAP response containing a collection of Response Objects. using SOAP 1.1 on server api.boomerangicomms.com returned the result of stdClass Object ( [GetAllResponsesWithinTheLast7DaysResult] => stdClass Object ( [Response] => Array ( [0] => stdClass Object ( [ResponseId] => 1208126 [OriginalMessageId] => 2329173 [OriginalMessageIdentifier] => my ID [RecipientsName] => Unknown [RecipientsMobileNumber] => +447836123456 [OriginatingNumberOrShortCode] => +447860001000 [Text] => R1 STM [IsNew] => 1 [DateSentToRecipient] => 2013-02- 11T06:37:13 [DateOfResponse] => 2013-02-11T06:37:53 ) [1] => stdClass Object ( [ResponseId] => 1208127 [OriginalMessageId] => 2329174 [OriginalMessageIdentifier] => my ID [RecipientsName] => Unknown [RecipientsMobileNumber] => +447836123456 [OriginatingNumberOrShortCode] => +447860001000 [Text] => R2 1 wk [IsNew] => 1 [DateSentToRecipient] => 2013-02- 11T06:38:04 [DateOfResponse] => 2013-02-11T06:38:34 ) [2] => stdClass Object ( [ResponseId] => 1210108 [OriginalMessageId] => 2332590 [OriginalMessageIdentifier] => my ID [RecipientsName] => Unknown [RecipientsMobileNumber] => +18179000000 [OriginatingNumberOrShortCode] => +16466000000 [Text] => Hello [IsNew] => 1 [DateSentToRecipient] => 2013-02-11T20:06:26 [DateOfResponse] => 2013- 02-11T20:06:57 ) [3] => stdClass Object ( [ResponseId] => 1210111 [OriginalMessageId] => 2332591 [OriginalMessageIdentifier] => my ID [RecipientsName] => Unknown [RecipientsMobileNumber] => +18179012345 [OriginatingNumberOrShortCode] => +16467777777 [Text] => Got it [IsNew] => 1 [DateSentToRecipient] => 2013-02- 11T20:06:39 [DateOfResponse] => 2013-02-11T20:07:22 ) ) ) ) and it took 0.097535848617554 seconds
Get New Responses This section defines the methods used to retrieve Recipient responses that have not been previously marked as read. Methods in this section
PUT Operations • getAllNewResponses • getAllNewResponsesByMessageId • getAllNewResponsesByMessageIdentifier • getAllNewResponsesByMobileNumber
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 34 of 55
getAllNewResponses
This operation will retrieve a list of all unread responses from Recipients associated to an organisation (within the previous 6 months). The method is structured as follows: getAllNewResponses {username, password, licenseKey, markAsRead} Below is a description of all the parameters required for this method: Parameter Description username password
licenseKey
markAsRead
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. Will mark all retrieved responses as read. Once marked as read, responses are not retrievable thereafter.
getAllNewResponsesByMessageId
This operation will retrieve a list of all responses to messages that have not been flagged as ‘read’ (using the ‘markAsRead’ method) using the message Id for the original outbound message, which is generated by Boomerang. When retrieving a response it is possible to mark it as read using the ‘markAsRead’ parameter. The method is structured as follows: getAllNewResponsesByMessageId {username, password, licenseKey, messageId, markAsRead} Below is a description of all the parameters required for this method: Parameter Description username password
licenseKey messageId markAsRead
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 is a mandatory field. Will mark all retrieved responses as read. Once marked as read, responses cannot be retrieved using any of the methods used to retrieve ‘new’ responses.
getAllNewResponsesByMessageIdentifier
This operation will retrieve a list of all responses to outbound messages that have not been flagged as ‘read’ (using the ‘markAsRead’ method) by custom identifier. A customer
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 35 of 55
identifier is a custom generated value that is passed to Boomerang as part of the original message request using the ‘customIdentifier’ parameter. It is also possible to mark new responses as read by using the ‘markAsRead’ parameter. The method is structured as follows: getAllNewResponsesByMessageIdentifier {username, password, licenseKey, customIdentifier, markAsRead} Below is a description of all the parameters required for this method: Parameter Description username password
licenseKey
customIdentifier markAsRead
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. 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. Will mark all retrieved responses as read. Once marked as read, responses cannot be retrieved using any of the methods used to retrieve ‘new’ responses.
Get All Responses (including previously marked as ‘read’) This section defines the methods used to retrieve responses that have been previously marked as read using the ‘markAsRead’ parameter which is included in all of the methods used to retrieve new responses. Methods in this section
GET Operations • getResponseById • getResponsesByMessageId • getResponsesByMessageIdentifier • getResponsesByRecipientsMobileNumber getResponseById
This operation will retrieve a single response to a message that was sent by a Recipient (Recipient) using the Id of the response, which is automatically generated by Boomerang. The method is structured as follows: getResponseById {username, password, licenseKey, responseId} Below is a description of all the parameters required for this method: Parameter Description username
The Boomerang account username. This is unique for every account in the system and is a mandatory, case sensitive field.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 36 of 55
password
licenseKey
ResponseId
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 given to the Recipient’s response, which is generated by Boomerang. This is a mandatory field.
getResponsesByMessageId
This operation will retrieve a list of all responses associated to a message, based on the original outbound message Id. This method would be used to retrieve responses to open ticket messages as open ticket messages can accept multiple responses. The original message Id that is automatically returned by Boomerang must be provided when making the request. The method is structured as follows: getResponsesByMessageId {username, password, licenseKey, messageId} Below is a description of all the parameters required for this method: Parameter username password
licenseKey messageId
Description 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 is a mandatory field.
getResponsesByMessageIdentifier
This operation will retrieve a list of all responses associated to a message based on a customIdentifier, which is provided by the customer as a parameter of the original outbound message request. This identifier must be provided when making the request. The main method looks like this: getResponsesByMessageIdentifier (username, password, licenseKey, customIdentifier) Below is a description of all the parameters required for this method: Parameter username password licenseKey
Description 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:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 37 of 55
customIdentifier
XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory, case sensitive field. A value generated by the customer’s application, which can be associated to a single message or to multiple messages. This is a mandatory field.
10.4 Retrieving responses via ‘Push’ This section describes how a Recipient’s response to a message can be accessed as a ‘push’ notification;; where data is automatically pushed to a pre-defined destination. All notifications are structured as ‘HTTP GET’. Push to a URL This allows a Recipient’s response to be automatically forwarded to a URL provided by the customer. The customer must ensure that the URL provided is available and that there are no restrictions preventing Boomerang’s messaging platform from reaching the customer’s platform (e.g. firewalls). On receipt of the response push, it is the customer’s responsibility to acknowledge receipt of the push notification by returning a response of ‘ok’ back to Boomerang. This will prevent further retry attempts. 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) • A structured example is provided below: • username => Apiusername • password => Apipassword123 • messageId => 7243 mobileNo => +447800123456 message => R1 dateSent => 2014-09-22 customIdentifier => my Id
The URL is manually configured by Boomerang on receipt of a customer’s request submitted to
[email protected] Methods is this section • addEndpointUrl • addUsernameAndPassword AddEndpointUrl
This operation will allow users to add, update or remove a webpage URL (e.g. https://www.exampleurl.com) as an endpoint to which all Recipient responses are forwarded. A null value must be passed to de-activate this service (by removing the URL). The method is structured as follows:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 38 of 55
addEndpointUrl {username, password, licenseKey, endpointUrl} Below is a description of all the parameters required for this method Parameter username password
licenseKey
endpointUrl
Description 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 end point URL to which all Recipient responses associated to a service account are forwarded.
The format of the inbound response delivered to the webpage will be as follows: https://www.exampleurl.com?messageId=xxxxx&mobileNo=xxxxxxxxx&message=xxx xxxxxxxxx&customIdentifier=xxxxxxx&dateSent=xxxxxxx&username=xxxxxx&passw ord=xxxxxxx addUsernameAndPassword
This operation will allow users to authenticate responses pushed by Boomerang by associating a username and password to the URL. The username and password will be delivered along with the URL as parameters, which can be used by the web page to authenticate the incoming request. The method is structured as follows: addUsernameAndPassword {username, password, licenseKey, pushUrlUsername, pushUrlPassword1} Below is a list of all the parameters required for this method: Parameter username password
licenseKey pushUrlUsername pushUrlPassword
Description 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 username to be included within the URL for validation. The password to be included within the URL for validation.
Note regarding use of the push service for Recipient responses
When inbound messages are forwarded by Boomerang to the destination URL there is no request for a notification from the web page at this point in time which prevents the service from engaging a retry mechanism in the event of a failure.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 39 of 55
Push to email Responses may 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 submitted to
[email protected].
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 40 of 55
11 Fixed inbound communications 11.1 Overview Using fixed inbound services allows an end user to initiate communication (Mobile Originated messaging) with an organisation via SMS, or to respond to 2-way broadcast communications that were initiated by an organisation (the response is not tracked against the outbound message for 2-way broadcast messages). Inbound services are configured using either a long or short inbound number, independently or with a keyword that must be assigned to a Boomerang service account (see table below for a description of each). This extends the opportunity to integrate Boomerang into workflow using an inbound message as the trigger.
11.2 Summary of inbound communication addresses A description of each type of inbound number is provided below: Inbound number type
Comms Channel
Exclusive long number (SMS)
SMS
Exclusive short number (SMS)
SMS
Shared short number (SMS)(must be used with a keyword)
SMS
Description A telephone number used to receive SMS messages normally comprising of eight or more digits that 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) that is assigned on a non- exclusive basis and must be used with a keyword that acts as a unique identifier for the organisation using the number.
*Short numbers native to Australia may contain up to 8 digits
11.3 Methods used to retrieve mobile originated messages The methods in this section the methods below describe how to retrieve all mobile originated inbound message data from a specific number or address registered in the Boomerang platform. All methods require a username, password and license key to relating to the service account against which the inbound number/address is associated. Elements of an inbound object Data Element Description Type
Integer String String String
String
String
Boolean
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
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 41 of 55
DateTime The date and time that the end user’s message was received
Methods in this section • getInboundMessages • getAllNewInboundMessages getInboundMessages
This method 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. The method is structured as follows: getInboundMessages {username, password, licenseKey, inboundNo, keyword} Below is a list of all the parameters required for this method: Parameter username Password
licenseKey
inboundNumber Keyword (optional)
Description 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 inbound number from which inbound message data is retrieved which is assigned to the Boomerang account. This is a mandatory field. The keyword from which inbound message data is retrieved which is assigned to the Boomerang account. This is an optional field.
NB: This method will not retrieve responses to outbound messages that have been sent using Boomerang’s Intelligent 2-way messaging. Responses to Intelligent 2-way messages are retrieved using the ‘GetResponse’ functions defined earlier in this document.
IMPORTANT: When polling the service for inbound message data please limit these requests to intervals of a least one minute. getAllNewInboundMessages
This method retrieves all inbound messages that have not been previously marked as ‘read’. 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 The method is structured as follows: getAllNewInboundMessages {username, password, licenseKey, inboundNo, keyword, markAsRead} Below is a list of all the parameters required for this method:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 42 of 55
Parameter username Password
licenseKey
inboundNumber Keyword (optional) markAsRead
Description 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 inbound number from which inbound message data is retrieved which is assigned to the Boomerang account. This is a mandatory field. The keyword from which inbound message data is retrieved which is assigned to the Boomerang account. This is an optional field. Will mark all retrieved inbound messages as read. Once marked as read, inbound messages are not retrievable thereafter.
11.4 Retrieving mobile originated messages by ‘Push’ This section describes how data can be received from an inbound address using a ‘push’ notification service, where the data is automatically pushed to a pre-defined URL address. Push to a URL Boomerang’s push service will automatically forward inbound messages to a pre-defined URL. The following data is included in the notification: • • • • • • •
Date / time of the inbound message Content of the response End user’s communication address Inbound number Keyword (if provided) Inbound Id Fixed Inbound Number reference (FIN ref)
A structured example is provided below: username => Apiusername password => Apipassword123 inboundId => 2969484 mobileNo => +447836669666 inboundNo => +447860001962 message => CRMQE IB1 220914 0719 keyword => CRMQE dateSent => 2014-09-22 timeSent => 07:21:02 finRef => This URL along with the optional username and password are manually configured by Boomerang on written request from the customer. All written requests should be submitted to
[email protected]
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 43 of 55
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 ‘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 address 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 written requests should be submitted to
[email protected].
11.5 Automated response messages Inbound SMS numbers may be configured with a pre-defined automated response that 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
[email protected].
11.6 Provisioning inbound services If you require any inbound services to be provisioned to your Boomerang account, please contact your Account Manager or Boomerang sales on +44 (0)20 7224 5555.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 44 of 55
12 Methods used to update message transactions 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. Methods in this section • markResponseAsReadByResponseId • markInboundAsReadByInboundId markResponseAsReadByResponseId
This operation will flag a response as read using the Id for that response. Once any new response has been marked as read it will be necessary to use the ‘Get Response’ rather than ‘GetNewResponse’ methods to retrieve that same response. The methods used to retrieve responses that have already been marked as read are covered in the next section. The method is structured as follows: markResponseAsReadByResponseId {username, password, licenseKey, responseId} Below is a description of all the parameters required for this method: 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
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 45 of 55
responseId
sensitive field. The Id given to the Recipient’s response, which is generated by Boomerang. This is a mandatory field.
markInboundAsReadByInboundId
This operation will flag an inbound message as read using the Id for that inbound message. Once any new inbound message has been marked as read it will be necessary to use the ‘getInboudMessage’ method to retrieve that same inbound message. The method is structured as follows: markInboundAsReadByInboundId {username, password, licenseKey, InboundId} Below is a description of all the parameters required for this method: Parameter Description username password
licenseKey
inboundId
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 given to the end user’s inbound message, which is generated by Boomerang. This is a mandatory field.
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 section describes how to close active message transactions. Methods in this section • closeTicketByMessageId closeTicketByMessageId
This operation is used to close a message prior to validity expiration using the original message Id returned by Boomerang. The method is structured as follows: CloseTicketByMessageId {username, password, licenseKey, messageId} Parameter username password licenseKey
Description 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:
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 46 of 55
messageId
XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory, case sensitive field. The id of the original outbound message. This is a mandatory field.
13 Methods used to query service account settings For customers using a trial, demo or pre-paid service, this operation allows the available message credit balance to be queried. Methods in this section • noOfCreditsAvailable noOfCreditsAvailable (Pre-payment, trial and demo accounts only)
Boomerang offers three 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) This method applies to pre-paid accounts that have purchased an allocation of message credits and will retrieve an integer value, notifying you how many credits remain on the account. The method looks like this: NoOfCreditsAvailable {username, username, licenseKey} The required parameters are defined below: Parameter username password
licenseKey
Description 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 47 of 55
14 Support Service requests regarding service-impacting issues are raised and monitored through our Technical Support case management system. Such requests must be raised directly by the customer via the method below: SUPPORT METHOD
CONTACT DETAILS
Email
[email protected] Customer originated requests: Any customer representative raising a ticket is required to provide their company details along with a description of the request and 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 48 of 55
15 Appendix 1 – SMS messaging technologies and character encoding 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. Please refer to the table below: Dec 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Hex 0 1 2 3 4 5 6 7 8 9 A B C D E F
0 0 @ £ $ ¥ è é ù ì ò Ç LF Ø ø CR Å å
16 10 Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ Æ æ É
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 to link the messages together. 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 49 of 55
An example of this is provided below: Number of SMS
Number of characters in the linked message
1 2 3 4 Etc.
160 characters 306 characters (2x153) 459 characters (3x153) 612 characters (4x153) 153 x Number of individual concatenated SMS messages
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
Number of characters in the linked message
1 2 3 4 Etc.
70 characters 134 characters (2x67) 201 characters (3x67) 268 characters (4x67) 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.
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 50 of 55
16 Appendix 2 – Error codes Code
Message content
400
‘Empty Message’
401
‘Invalid User’
400
‘Invalid IP’
400
‘Invalid number format’
400
‘Not enough credits’
400
‘No Dynamic Header’
400
‘No Preferred Number’
500
‘Internal error’ Unsupported HTTP method
501
Message Description The message cannot be sent as there is no message content provided with the request. Please ensure that the 'textMessage' 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 insufficient message credits on the account (Trial and Pre- paid customers only) No value has been passed in the dynamicHeader parameter when using the method sendTextMessageWithDynamicHeader No value has been passed in the preferredMobileNumber parameter when using the method sendTextMessageWithPreferredNumber An internal within Boomerang occurred An unsupported HTTP method is being used
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 51 of 55
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 52 of 55
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 Guadeloupe Guam
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 GLP GUM
Prefix +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 +590 +1671
Name
ISO Code
Prefix
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 Syria Taiwan
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 SYR TWN
+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 +963 +886
Guatemala Guinea Guyana Haiti Honduras Hong Kong Hungary Iceland India Indonesia Iran Iraq Ireland Israel Italy Jamaica Japan Jordan Kenya Kiribati Kuwait
GTM GIN GUY HTI HND HKG HUN ISL IND IDN IRN IRQ IRL ISR ITA JAM JPN JOR KEN KIR KWT
+502 +224 +592 +509 +504 +852 +36 +354 +91 +62 +98 +964 +353 +972 +39 +1876 +81 +962 +254 +686 +965
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
TJK TZA THA TKL TUN TUR TKM TUV UGA UKR GBR USA URY UZB VUT VAC VEN VNM YEM ZMB ZWE
+992 +255 +66 +690 +216 +90 +993 +688 +256 +380 +44 +1 +598 +998 +678 +39 +58 +84 +967 +260 +263
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 54 of 55
18 Appendix 4 - Summary of API methods No. 1 2 3 4 5 6 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Method noOfCreditsAvailable sendTextMessage sendTextMessageWithDynamicHeader sendTextMessageWithCustomNumber sendTextMessageWithPreferredNumber sendEmailMesage getMessageById getAllNewResponses getAllNewResponsesByMessageId getAllNewResponsesByMessageIdentifier getAllNewResponsesByMobileNumber markResponseAsReadByResponseId getResponseById getResponsesByMessageId getResponsesByMessageIdentifier getResponsesByRecipientsMobileNumber addEndpointUrl addUsernameAndPassword closeTicketByMessageId getInboundMessages getAllNewInboundMessages markInboundAsReadByInboundId
SOAP_API_Specification_and_Integration_Guide_BMr233_v1.1.docx
Page 55 of 55
