Business Messenger SMS - SDK

Prerequisites

To proceed with the integration of SMS Form SDK to your HTTPS web site you must meet the following conditions:

  • Locate your Form configuration from HORISEN Business Messenger Application
  • Download or use SMS Form SDK

1. Introduction

SMS Form SDK is a javascript library that provides a subscription mechanism for SMS messages for your website.

After a visitor subscribes you will be able to send him SMS messages using standard Business Messenger campaigns.

The SDK can be used directly from javascript so that you can build your own custom subscription forms and collect some other information to be populated per contact in Business Messenger Contact Manager.

2. Setup

The Business Messenger App Account

It is implied that the user has the Business Messenger app account and can access it.

The Business Messenger App Web Form

In the Business Messenger App go to the Web > Web Forms section, create a Web Form, and find your configuration in the Detailed View for the form (click the view icon from the grid last column). You will need the presented SDK Parameters later in configuring the SDK.

3. Integration

Initialize SDK

Include the SDK script in your page:

<script type="text/javascript" src="https://content.horisen.pro/js/ngage-sms-form/sdk/latest/hpro-sms-form-sdk.min.js"></script>

Initialize the SDK:

<script>
    window.hproSMSFormAsyncInit = function() {
        window.SMSForm = hproSMSForm.initForm({
            url: "https://api{separator}{platform_domain}/news/v1/forms/b9cc91fa-8f76-4dd1-bddf-0fb2ddca757e", //Replace with valid URL
        });
    }
</script>

Set configuration and SDK just before the end of </body> tag

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

Google reCaptcha

reCAPTCHA protects against spam and other types of automated abuse.
Google reCaptcha is to be implemented by the developer who is implementing this SDK.
reCaptcha sitekey that is needed for reCaptcha initializing, can be found in the Business Messenger app, the Web > Web Forms section, under the Form Detailed View (click the view icon from the grid for the Form).

More info about implementing Google reCaptcha please find on Google Guides pages.

4. Configuration SDK Properties

Property Type Params Description
initForm function Object
Key Type Description Required
url string Defines Form and API URL. Yes
Parameters are obtained in the Business Messenger app after creating SMS Web Form, under form view from the grid.
Usage

After SDK is initialized we can now use it to subscribe or unsubscribe users.
Subscribing or unsubscribing is a two-step process. After submitting the form, "code" is sent to users' mobile number via SMS. That code must be sent in the second step.

First step example:

let data = {
    identifier: '+12025550183',
    option_uuids: 'fac1f6dd-e11b-4ab6-9812-a03302812233,1d722df4-1b3a-1ff1-81d2-d76075b12677',
    recaptcha: "03AGdBq24kHszPYZ85tzyVMU-C2uN998wWzWJDZnHCyyZQoKScVgFWvT28b21Q67DaNgYFg5kCvl1T...", // recaptcha code is much longer than in this example
    type: 'in'
};
window.SMSForm.submitForm(data).then(function(res){
    // on request success
    // here we can now enable part of the form where user can input code that he recived on his mobile phone
    // we need to reset recaptcha here
}).catch(function(err){
    // on request error
    // here we can notify user that there was an error and to try again
    // we also need to reset recaptcha here
});

After the first step is successful, we need to send code that the user received on his mobile phone via SMS message.

Second step example:

let data = {
    code: '6465865',
    //here we can send additional data about user
    first_name: 'John',
    last_name: 'Smith'
}
window.SMSForm.submitCode(data).then(function(res){
    //on request success
    // here we can reset all form data and allow for another subscription
}).catch(function(err){
    // on request error
    // if error is invalid code than we can inform user and ask him to enter it again or notify about error and reset form
});
Property Type Params
submitForm function Object
Key Type Values Description Required
identifier string Mobile phone number of a user that is subscribing/unsubscribing in international format Yes
option_uuids string Coma separated array of option UUIDs witch users selected to subscribe/unsubscribe to/from. No
recaptcha string ReCaptcha code. ReCaptcha is implemented by the form using SDK Yes
type string in
out 		Defines if the form is used to subscribe (in) or unsubscribe (out) the user Yes
submitCode function Object

If the form is used to unsubscribe the user ("type": "out"), then additional user data will not be saved so there is no need to send them.
If additional user data is sent it will be ignored by API.

Key Type Values Description Required
code string Code that the user received on his mobile phone. The code must be obtained from the user and submitted so that we know it is really him who is subscribing. Yes
first_name string First Name No
last_name string Last Name No
nick_name string Nick Name No
second_name string Second Name No
gender string male
female		 Gender
Female -or- Male 		No
birthday string Birthday Format: 2018-01-03 No
salutation string Salutation No
fax string Fax No
language string (lowercase) https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes Language Example: 'en' for English No
nationality string (uppercase) https://en.wikipedia.org/wiki/ISO_3166-1 Nationality Example: "GB" for United Kingdom No
mobile string Mobile Example: +41 78 123 45 67 No
phone string Phone Example: +41 78 123 45 67 No
title string Title No
zip string Zip No
address string Address No
city string City No
region string Region No
country string (uppercase) https://en.wikipedia.org/wiki/ISO_3166-1 country Example: "GB" for the United Kingdom No
b_address string Business address No
b_city string Business city No
b_company string Company name No
b_country string (uppercase) https://en.wikipedia.org/wiki/ISO_3166-1 Bussiness Country example: 'DE' for German No
b_department string Business Department No
b_email string Business Email No
b_job_title string Job Title No
b_mobile string Business Mobile Example: +41 78 123 45 67 No
b_phone string Business Phone Example: +41 78 123 45 67 No
b_reception_code string Bussiness Reception code No
b_region string Business Region No
b_zip string Business Zip No

5. Example

Here is a working example of SDK in action. In order for this example to work all parameters should be replaced with real ones and run in a localhost environment (e.g. http://localhost:3000/).

Note that the port number can be changed. 

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>SMS SDK Example</title>
        <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
    </head>
    <body>

        <!-- Step 1 -->
        <form id="step1">
            <h1>Web SMS - Opt IN with options</h1>
            <div id="identifier">
                <input type="tel" name="identifier" placeholder="Mobile" required>
            </div>

            <div id="first_name">
                <input name="first_name" type="text" placeholder="First name" required />
            </div>

            <div id="last_name">
                <input name="last_name" type="text" placeholder="Last name" required />
            </div>

            <div id="options">
                <!-- Replace with valid option uuid -->
                <div class="form-group form-group-checkbox">
                    <input type="checkbox" id="fac1f6dd-e11b-3333-5555-a0330281aa67"
                        name="fac1f6dd-e11b-3333-5555-a0330281aa67"
                        value="fac1f6dd-e11b-3333-5555-a0330281aa67" data-option="subscription">
                    <label for="fac1f6dd-e11b-3333-5555-a0330281aa67"> Audi </label>
                </div>
                <!-- Replace with valid option uuid -->
                <div class="form-group form-group-checkbox">
                    <input type="checkbox" id="1d722df4-1b3a-3333-5555-d76075b12677"
                        name="1d722df4-1b3a-3333-5555-d76075b12677"
                        value="1d722df4-1b3a-3333-5555-d76075b12677" data-option="subscription">
                    <label for="1d722df4-1b3a-3333-5555-d76075b12677"> BMW </label>
                </div>
            </div>

            <div id="recaptcha">
                <!-- Replace with valid sitekey -->
                <div class="g-recaptcha" data-sitekey="6LdjduIBRRRRRU-oJrqdQDmpALmlRtXMPxTYhFDN"></div>
            </div>

            <button id="submit-btn-step1" type="button" class="btn btn-outline" onclick="sendForm(event)" style="margin-top:15px"> Subscribe </button>
        </form>

        <!-- Step 2 -->
        <form id="step2" hidden="hidden">
            <h1>Did you get sms?</h1>
            <h4>Now you can enter it in the field</h4>
            <div id="code">
                <input name="code" type="text" placeholder="code" required />
            </div>
            <button id="submit-btn-step2" type="button" onclick="sendCode(event)" style="margin-top:15px">Verify</button>
        </form>

        <script>
            var getFieldsValues = function (fields) {
                if (!fields || fields.length <= 0) return [];
                var values = {};
                for (var i = 0; i < fields.length; i++) {
                    if (!fields[i] || fields[i].value == '') continue;

                    if (fields[i].type == 'checkbox' && fields[i].checked === false) continue;

                    values[fields[i].name] = fields[i].value;
                }
                return values;
            };

            // Init SDK
            window.hproSMSFormAsyncInit = function () {
                window.SMSForm = hproSMSForm.initForm({
                    url: 'https://api{separator}{platform_domain}/news/v1/forms/0e0a4296-062a-40e9-3333-002aa27e5679', //Replace with valid URL
                });
            }

            var formData = {};

            function sendForm(e) {
                e.preventDefault();

                //Get all fields inside form
                var formFields = $("#step1 input");

                //Get fields values from form
                var formFieldsValues = getFieldsValues(formFields);

                // reCaptcha Validation
                var recaptchResponse = grecaptcha.getResponse();

                // if options_uudi is defined this field will be validate
                var options = $('#options input');
                if (options && options.length > 0) {
                    var formOptionsValues = getFieldsValues(options);
                }

                // Get personal data for step 2 in formData variable
                formData['first_name'] = formFieldsValues['first_name'];
                formData['last_name'] = formFieldsValues['last_name'];
                var selectedOptions = [];

                var formElements = document.getElementById('step1').elements;
                for (var i = 0; i <= formElements.length - 1; i++) {
                    if (formElements[i].id == 'g-recaptcha-response'
                        || formElements[i].name == 'identifier'
                        || formElements[i].id == 'submit-btn-step1'
                    ) {
                        continue;
                    }

                    if (formElements[i].dataset.option === 'subscription') {
                        if (formElements[i].checked) {
                            selectedOptions.push(formElements[i]['value']);
                        }
                        continue;
                    }
                    formData[formElements[i]['name']] = formElements[i]['value'];
                }

                // Parameters for submitForm sdk action
                var param = {
                    identifier: formFieldsValues['identifier'],
                    option_uuids: selectedOptions.toString(),
                    recaptcha: recaptchResponse,
                    type: 'in'
                };

                // Actual submit
                window.SMSForm.submitForm(param).then(function (res) {
                    $('#step1').attr('hidden', 'hidden');
                    $('#step2').removeAttr('hidden');
                }).catch(function (err) {
                    grecaptcha.reset();
                });
            }

            function sendCode(e) {
                e.preventDefault();
                //Get all fields inside form
                var formFields = $("#step2 input");
                //Get fields values from form
                var formFieldsValues = getFieldsValues(formFields);
                // Parameters for submitCode sdk action
                var param = formData;
                param['code'] = formFieldsValues['code'];
                window.SMSForm.submitCode(param)
                    .then(function (res) {
                        document.getElementById("step1").reset();
                        document.getElementById("step2").reset();
                        grecaptcha.reset();

                        $('#step2').attr('hidden', 'hidden');
                        $('#step1').removeAttr('hidden');
                    }).catch(function (err) {
                        if (err.error && err.error.message == 'Invalid code') {
                            $('#code').append('<span class="error">Invalid code</span>');
                            return;
                        }
                        document.getElementById("step2").reset();
                        $('#step2').attr('hidden', 'hidden');
                        $('#step1').removeAttr('hidden');
                        grecaptcha.reset();
                    });
            }
        </script>
        <script src="https://www.google.com/recaptcha/api.js" async defer></script>
        <script src="https://content.horisen.pro/js/ngage-sms-form/sdk/latest/hpro-sms-form-sdk.min.js"></script>
    </body>
</html>