Tutorial - SMS Engage

Introduction

8x8 offers API methods that allow you to send SMS Engage programmatically.
In this tutorial, we will cover how to send a single SMS Engage: Send SMS Engage survey and multiple SMS Engage: Send SMS Engage surveys as batch in one command.

Index

  • Learn how to use the method for sending SMS Engage SMS
  • Prerequisities
  • Account and Credentials
  • Components of API Request
  • Preparing request URL
  • Data Payload (Single and Bulk SMS Engage)
  • Testing the request with Curl

Prerequisites

  • Command line interface compatible with CURL
  • 8x8 account with SMS Engage form and activated with your subaccount.
  • apiKey (Bearer token)
  • 8x8 CPaaS subaccountid
  • Destination phone numbers

Account and credentials

You will need to sign-up to use the API. The following steps will guide you through this process and highlight the information to keep aside.

I. Signing-up

  1. Head to 8x8 Connect sign-up page
  2. Enter your email and follow the instructions to define your password and finalize your account (by default, API password and account password are the same, you can modify this from your account settings)
  3. Confirm your email address by clicking on the validation link you received in the activation email to activate your account.
2408

II. Finding your apiKey bearer token (for API authentication)

  1. Head to 8x8 Connect Login Page.
  2. Click on LOG IN.
  3. Enter your email address and password to get access to your account dashboard.
  4. Head over to the side menu > API keys section
  5. Create an API key if empty and then keep the API Key value, here: 12345bWI3sRZzP5iSDxttmEse82Vt1NMUwf3aideJQ
1600

You must have your account activated to use SMS Engage and at least one SMS Engage form created for you by 8x8. SMS Engage forms are created based on your use-cases. Once they are created, 8x8 will provide you a surveyid and url.

  • Please note that the variable url is your default SMS Engage link which 8x8 has set up for you (e.g. http://smstoweb.net?sid=1234). The url is shortened once the message has been sent.
    The shortened url is always 21 characters in length.
  • If you want to get the data via Webhooks, simply provide us a specific url where we will post the data.
  • For more information please contact your account manager or contact the product team

III. Identifying your Subaccountid

  1. Head over to the pricing section and use the subaccountid list to retrieve the subaccountid that you want to use
  2. By default, your account comes with only one subaccountid for your high-quality service. It is designated by your accountid and the suffix _hq.
  3. Note down this value, you will need it later.
  4. In that example, the subaccountid is sliders_hq.
1600

API Request

The 8x8 SMS Engage survey method expects requests sent by developers to respect a specific format.
In the following parts, we are going to go over the different elements of the request:

  • URL format
  • Authentication
  • Data payload

At the end of the section, we will generate a curl command to send an SMS Engage directly from the command line.

I. Preparing the request URL

Remarks
  • We are going to send a POST request to the 8x8 API Engage URL endpoint.
  • As detailed in the Send SMS Engage survey , the URL is defined by the following pattern: https://sms.8x8.com/api/v1/subaccounts/{subAccountId}/surveys/{surveyId}/messages
Tutorial URL - Single SMS Engage
  • In order to create the URL to use, we are going to replace {subaccountid} in the pattern above by sliders_hq, the subaccountid that we are using in this tutorial. The surveyId that will be provided to you once your SMS Engage form is generated, the surveyId for this tutorial is nps_survey.
  • Now replace subAccountId with your subaccountid and surveyId
  • In this example, the URL that we are going to send the request to is:
    https://sms.8x8.com/api/v1/subaccounts/sliders_hq/surveys/nps_survey/messages

Data payload

The API expects to receive a structured request containing the SMS data in a specific format. As detailed in the documentation, the data that we have to submit should be a JSON object.

For simplicity sake, we are going to use only the most important of the parameters (the others are detailed in the documentation)

To send a single SMS Engage message here is an example of a data payload:

{
 "destination": "+6596790611",
 "templateBody": "Hello! Take a survey here: {{url}}",
 "templateVariables": {
     "url": "https://smstoweb.net?sid=14344"
 },
 "source": "Acme"
}

Destination - mobile phone number in international format (e.g. +6596728122)
TemplateBody - Template of message to user. It should have the variable {{url:}} which is the default link set for you by 8x8.
TemplateVariables - variables or pre-defined fields used inside the templateBody. Your url should have the value or link set for you by 8x8.
Source - SenderId or β€œFrom:” field for the SMS Engage

Tutorial URL - Batch SMS Engage
  • In order to create the URL to use, we are going to replace {subaccountid} in the pattern above by sliders_hq, the subaccountid that we are using in this tutorial. The surveyId that will be provided to you once your SMS Engage form is generated, the surveyId for this tutorial is nps_survey.
  • Now replace subAccountId with your subaccountid and surveyId
    https://sms.8x8.com/api/v1/subaccounts/sliders_hq/surveys/nps_survey/messages/batch

Data payload

To send a bulk SMS Engage message here is an example of a data payload:

{
   "template": {
       "source": "WL INFO",
       "templateBody": "Hello; please take your survey {{url}}"
      
   },
   "messages": [
       {
           "destination": "+6596790611",
           "templateVariables": {
               "url": "https://smstoweb.net?sid=5468605"
           }
       },
       {
           "destination": "+639173375856",
           "templateVariables": {
               "url": "https://smstoweb.net?sid=5468605"
           }
       },
       {
           "destination": "+639179450911",
           "templateVariables": {
               "url": "https://smstoweb.net?sid=5468605"
           }
       }
   ]
}

These two JSON objects should be set within an object called β€œtemplate”
TemplateBody - Template of message to user. It should have the variable {{url:}} which is the default link set for you by 8x8.
Source - SenderId or β€œFrom:” field for the SMS Engage

The next group of objects should be set within an object called β€œmessages” namely
Destination - mobile phone number in international format (e.g. +6596728122)
TemplateVariables - variables or pre-defined fields used inside the templateBody.
Your url should have the value or link set for you by 8x8.

Putting it altogether and testing it with cURL

Now that you have all the data you need, let’s try this by using cURL. If you are on MAC, cURL is already installed. Just run the Terminal app (Located under Applications->Utilities).

For Windows based machines click here on how to install curl.

889

To test this we should use the following command in our terminal or any command tool utility like this:

(single SMS Engage)

curl -X "POST" https://sms.8x8.com/api/v1/subaccounts/sliders_hq/surveys/nps_survey/messages 
-H "Authorization: Bearer 12345bWI3sRZzP5iSDxttmEse82Vt1NMUwf3aideJQ" 
-H "Content-Type:application/json" 
-d $'{
   "destination": "+6596790611", "templateBody": "Hello! Take a survey here{{url}}","templateVariables": {"url": "https://smstoweb.net?sid=14344"},"source": "Acme"
    }'

Just replace the destination number to your mobile number so you can receive the message and click the SMS Engage link.