May 4, 2016 - responses by sending an email notification containing the response ...... 'batch' requests by specifying t
RESTful API Specification & Integration Guide Boomerang r2.3.5 Author Document Version Date
Andy Allen 1.5 4th May 2016
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 Context – Intelligent 2-way Messaging ...................................................................................... 6 Purpose ...................................................................................................................................... 6 Scope .......................................................................................................................................... 6 References ................................................................................................................................. 7 Definitions .................................................................................................................................. 7 Preparing for integration ........................................................................................................... 9 6.1
Connectivity settings..................................................................................................... 9 Proxy servers ................................................................................................................. 9 Email messages sent using the method ‘SendEmailMessage’ ...................................... 9
6.2
Account settings ........................................................................................................... 9
6.3
API Security ................................................................................................................... 9 API Key .......................................................................................................................... 9 Username and Password ............................................................................................ 10 Restrict access by IP address ...................................................................................... 10
6.4
?> 24686 D 2015-05-04T01:57:30 24696 U 2015-05-11T21:57:20 24697 U 2015-05-11T21:57:20 24705 U 2015-05-11T23:33:20 24706 U 2015-05-11T23:33:21
11.4 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 responses Whether the validity period of the message has expired Boomerang will be unable to match the recipient’s response with a message ticket.
A single method is used to retrieve response ?> 3331213 +447812345678 +447860001962 SMSEQ Msg1 12:45 24/5 SMSEQ Y 2016-05-24T12:45:35
When polling the service for inbound message data, please limit these requests to intervals of a least one minute.
12.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 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:
Username and password A unique Id for the inbound message The originating address submitting the inbound message The inbound number to which the message was submitted The content of the inbound message A matched keyword (if included within the inbound message) The date and time at which the inbound message arrived at the Boomerang platform A reference associated to the inbound number (if configured in the Boomerang platform)
BMr235RAPISv1.5
Page 40 of 52
A structured example is provided below: username => Apiusername password => Apipassword123 inboundId => 2969484 mobileNo => +447812345678 inboundNo => +447860001962 message => CRMQE IB1 220914 0719 keyword => CRMQE dateSent => 2014-09-22 timeSent => 07:21:02 finRef => My fixed inbound ref
This URL along with the (optional) username and password are manually configured by Boomerang on written request from the customer. All requests should be submitted to
[email protected] Retry process for push service Where Boomerang identifies that a response message has not been successfully forwarded to the URL provided a retry process is invoked.
3 retries immediately after a failure 5 minute intervals thereafter up to 24 hours
Push to an 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 requests should be submitted to
[email protected].
12.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].
12.6 Provisioning inbound services To request any of the inbound services described in this section, please contact your Account Manager or Boomerang sales on +44 (0)20 7224 5555.
BMr235RAPISv1.5
Page 41 of 52
Methods used to update message transactions The operations in this section enable the status of outbound, inbound and response messages to be updated.
13.1 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 MarkResponseAsRead MarkInboundAsRead MarkResponseAsRead
Marking a response or responses as ‘read’ allows a user to specify that only new (unread) data is retrieved when making subsequent requests to the ‘GetResponse’ function. Below is a description of all the parameters required for this method: Parameter
BMr235RAPISv1.5
Mandatory
Description
Page 42 of 52
/ Optional username
M
password
M
licenseKey
M
responseId
M
Boomerang account username. This is unique for every account in the system and is a mandatory, case sensitive field. Boomerang account password. A password must contain: a minimum of 8 characters, at least one upper and lower case character and one digit. This is a case sensitive field. A unique API key is automatically generated on creation of every Boomerang account. Consisting of 35 characters, the API key adheres to the following format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXXXXXXX. This is also a mandatory, case sensitive field. The Id for the response that is matched to the originating outbound message. This is retrievable using the ‘GetResponses’ function.
MarkInboundAsRead
Marking an inbound message or multiple inbound messages as ‘read’ allows a user to specify that only new (unread) data is retrieved when making subsequent requests to the ‘GetInbound’ function. Below is a description of all the parameters required for this method: Parameter Mandatory Description / Optional username
M
password
M
licenseKey
M
inboundId
M
Boomerang account username. This is unique for every account in the system and is a mandatory, case sensitive field. Boomerang account password. A password must contain: a minimum of 8 characters, at least one upper and lower case character and one digit. This is a case sensitive field. A unique API key is automatically generated on creation of every Boomerang account. Consisting of 35 characters, the API key adheres to the following format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXXXXXXX. This is also a mandatory, case sensitive field. The inbound Id that is associated to the inbound message. This is retrievable via the ‘GetInbound’ function.
13.2 Methods used to close message transactions Where a recipient response is longer required but the message remains active as the validity expiration period has not been reached, the message can be manually closed. This could be used where a specific System Virtual Number is required (using the preferredMobileNo parameter). This section describes how to close active message transactions. Methods in this section CloseTicket CloseTicket
This operation is used to close a message prior to validity expiration using the message Id associated to the outbound message, which is automatically generated by Boomerang. Below is a description of all the parameters required for this method: Parameter Description username
BMr235RAPISv1.5
The Boomerang account username. This is unique for every account in the
Page 43 of 52
system and is a mandatory, case sensitive field. The Boomerang account password. A password must be at least 8 characters in length and consist of at least one upper and lower case character and at least one digit. This is a mandatory, case sensitive field. A unique API key is automatically generated on creation of every Boomerang account. Consisting of 35 characters, the API key adheres to the following format: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX. This is also a mandatory, case sensitive field. The id of the original outbound message. This can be retrievable via the ‘GetMessage’ function.
password
licenseKey
messageId
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-paid, trial or demo accounts only)
Boomerang offers three types of customer account: o o o
Trial accounts (provisioned automatically and free messages allocated) Demo accounts (provisioned by Boomerang and free messages credits allocated) Pre payment (messages purchased in advance)
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. 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
password
licenseKey
BMr235RAPISv1.5
Page 44 of 52
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.
Reporting It is possible to retrieve transactional message data from Boomerang by submitting an email request. On receipt of a valid request, a .csv file containing transactional message data between the dates requested is returned to the sender’s email address.
15.1 Service parameters Composing a new mail message Requests to the service are accepted from any email client or server (e.g. Outlook, Exchange, Hotmail etc) and should be submitted by email to
[email protected]. For a request to the reporting service to be processed successfully, of parameters must be provided along with a value for that parameter. The table below provides: 1. The required format for each parameter 2. A description of each parameter 3. The value required for each parameter and the appropriate syntax for that value Parameter syntax
Description
Parameter value syntax
Startdate:
The date from which message data will be provided in the .csv file report. This is a mandatory parameter. The date up to which message data will be included in the .csv file report. This is a mandatory parameter. An email address to which the .csv report will be sent in addition to the sender’s email address. This is an optional parameter.
dd/mm/yyyy
Enddate:
Extraemail:
dd/mm/yyyy
Single email address e.g
[email protected]
Boomerang will only return a report containing up to a maximum of 5,000 records in a single request.
BMr235RAPISv1.5
Page 45 of 52
15.2 Authentication Access to the service is secured by registering authorised an email address or email domain against your Boomerang account. To do this, please submit a request to
[email protected]
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.
BMr235RAPISv1.5
Page 46 of 52
Appendix 1 – SMS messaging technologies and character encoding 17.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 (7bit) 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. An example of this is provided below: Number of SMS 1 2 3 4 Etc.
Number of characters in the linked message 160 characters 306 characters (2x153) 459 characters (3x153) 612 characters (4x153) 153 x Number of individual concatenated SMS messages
17.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,
BMr235RAPISv1.5
Page 47 of 52
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. Multipart or concatenated messages containing 16-bit encoded characters are delivered as a single message but will be billed in 67 character segments. See below: Number of SMS 1 2 3 4 Etc.
Number of characters in the linked message 70 characters 134 characters (2x67) 201 characters (3x67) 268 characters (4x67) 67 x Number of individual concatenated SMS messages
17.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.
BMr235RAPISv1.5
Page 48 of 52
Appendix 2 – Error codes Code
Message content
Message Description
400
‘Empty Message’
400
‘Invalid User’
400
‘Invalid IP’
400
‘Invalid number format’
400 400
‘No Mobile Numbers’ ‘Too Many Mobile Numbers’ No Email Addresses Too Many Email Addresses ‘No Telephone Numbers’ ‘Too Many Telephone Numbers’ ‘Not enough credits’
The message cannot be sent as there is no message content provided with the request. Please ensure that the 'text' parameter has been completed. The credentials provided are not valid or the account is not active The IP address from which the requests originated is not accepted by Boomerang The mobile number provided is not formatted correctly and contains too few or too many digits (less than 10 or more than 20) There are no telephone numbers contained in the request More than 50 telephone numbers were included in the request
400 400 400 400 400 500 501
‘Internal error’ Unsupported HTTP method
BMr235RAPISv1.5
There are no email addresses contained in the request More than 50 email addresses were included in the request There are no telephone numbers contained in the request More than 50 telephone numbers were included in the request There are insufficient message credits on the account (Trial and Pre-paid customers only) An internal within Boomerang occurred An unsupported HTTP method is being used
Page 49 of 52
Appendix 3 – TTS (Voice) call flow
BMr235RAPISv1.5
Page 50 of 52
Appendix 4 - Summary of API methods No. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.
Method NoOfCreditsAvailable SendThreadedMessage SendTextMessage SendEmailMesage SendVoiceMesage GetMessage GetAllNewDrs GetResponses GetInbound MarkResponseAsRead MarkInboundAsRead CloseTicket
BMr235RAPISv1.5
Page 51 of 52
Document change management Date 4th May 2016 28th April 2016 26th Feb 2016 11th Nov 2015 9th April 2015 10th Feb 2014
BMr235RAPISv1.5
Version Description 1.5 Addition of ‘priority’ parameter in send SMS functions and Reporting section 1.4 Appendix 3 - TTS (Voice) call flow inserted 1.3 Updates to content regarding structure of push notifications 1.2 GetLatestDRs method added 1.1 Style and formatting changes 1.0 Original version
Page 52 of 52
