Tutorial: Learn how to use API to send 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 and multiple SMS Engage in one command.

This tutorial assumes you have an account with us and you have already requested an SMS Engage form and activated with your subaccount. If you have not done this already, you can sign up here. Once signed up, please contact our sales team to help you understand more and enable this feature for you.

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

What you will need

  • Subaccountid and an API key (see below for where to find them) 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

API and Subaccount ID

For API authentication, you will need an API Key. Your API key(s) are located under the API Keys management section (Just click “API Keys” on the left side menu).

API Key

By default, an API Key is generated for you but if you need more, just create another API key. On this page you will also find your subaccountid which you will use later. From the image above the subaccountid is sliders_hq and the API key is 12345bWI3sRZzP5iSDxttmEse82Vt1NMUwf3aideJQ

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.

Preparing the request URL

We are going to send a POST request for this url endpoint. As detailed in the documentation, the URL is defined by the following pattern: https://api.wavecell.com/survey/v1/{subAccountId}/{surveyId}/single

Now replace subAccountId with your subaccountid and surveyId with the surveyid that we will provide for you once your SMS Engage form is generated. Your url now will look something like this

https://api.wavecell.com/survey/v1/sliders_hq/nps_survey/single

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

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.

API Key

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://api.wavecell.com/survey/v1/sliders_hq/nps_survey/single 
-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.