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 SMS.es 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 Services > 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.sms.es.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 Services” > “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 | ObjectKeyTypeDescriptionRequiredurlstringDefines 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 | ObjectKeyTypeValuesDescriptionRequiredidentifierstringMobile phone number of a user that is subscribing/unsubscribing in international formatYesoption_uuidsstringComa separated array of option UUIDs witch users selected to subscribe/unsubscribe to/from.NorecaptchastringReCaptcha code. ReCaptcha is implemented by the form using SDKYestypestringin outDefines if the form is used to subscribe (in) or unsubscribe (out) the userYes |
| submitCode | function | ObjectIf 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.KeyTypeValuesDescriptionRequiredcodestringCode 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.Yesfirst_namestringFirst NameNolast_namestringLast NameNonick_namestringNick NameNosecond_namestringSecond NameNogenderstringmale femaleGender Female -or- MaleNobirthdaystringBirthday Format: 2018-01-03NosalutationstringSalutationNofaxstringFaxNolanguagestring (lowercase)https://en.wikipedia.org/wiki/List_of_ISO_639-1_codesLanguage Example: ‘en’ for EnglishNonationalitystring (uppercase)https://en.wikipedia.org/wiki/ISO_3166-1Nationality Example: “GB” for United KingdomNomobilestringMobile Example: +41 78 123 45 67NophonestringPhone Example: +41 78 123 45 67NotitlestringTitleNozipstringZipNoaddressstringAddressNocitystringCityNoregionstringRegionNocountrystring (uppercase)https://en.wikipedia.org/wiki/ISO_3166-1country Example: “GB” for the United KingdomNob_addressstringBusiness addressNob_citystringBusiness cityNob_companystringCompany nameNob_countrystring (uppercase)https://en.wikipedia.org/wiki/ISO_3166-1Bussiness Country example: ‘DE’ for GermanNob_departmentstringBusiness DepartmentNob_emailstringBusiness EmailNob_job_titlestringJob TitleNob_mobilestringBusiness Mobile Example: +41 78 123 45 67Nob_phonestringBusiness Phone Example: +41 78 123 45 67Nob_reception_codestringBussiness Reception codeNob_regionstringBusiness RegionNob_zipstringBusiness ZipNo |
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.sms.es.pro/js/ngage-sms-form/sdk/latest/hpro-sms-form-sdk.min.js"></script>
</body>
</html>
