Skip to main content

 

 
8x8 Support

SMS API Setup

  1. Last updated
  2. Save as PDF

SMS API Setup

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.

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.

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.

Finding your API key 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

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.

  • 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

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.

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

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's 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 all together 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.

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

(single SMS Engage)