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.

Video Demo

This video below will take you through a demo of SMS Engage including: sending a survey via API, filling out a survey and viewing the responses on the Connect Dashboard.

Prerequisites

• 8x8 Account with an SMS Engage form created
  • If you do not have an SMS engage form, see the SMS Engage Form section below on how to obtain one.
• 8x8 API Key
  • Please see this page on how to create API Keys if you do not have an existing one.

SMS Engage Form

You must have 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_ac*.

• 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 on how to create an SMS engage form please contact your account manager or send an email to 8x8 Support.

Send Single SMS Engage Survey

The 8x8 SMS Engage survey method expects requests sent by developers to respect a specific format.

In the following section, 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.

Request URL

• 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
  • The {subAccountID} should be replaced by your own 8x8 Subaccount ID and the {surveyId} should be replaced by your Survey ID in a request.

Authentication

Use your API Key in the Authorization header of your HTTP request, this is denoted with the variable below.

curl --location 'https://sms.8x8.com/api/v1/subaccounts/<subaccount>/surveys/<surveyId>/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: <apiKey>' \

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.

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

{
  "destination": "<mobileNumber>",
  "templateBody": "Hello {{firstName}}, your order is {{order_nr}}. {{url}} Please check and confirm if your scheduled delivery time is ok.",
  "templateVariables": {
    "firstName": "James",
    "order_nr": "ABC1000"
  },
  "source": "<sourceVnOrSenderId>"
}

The JSON parameters are explained in the table below:

Sending the API Request

Now that the API request is setup correctly you need, let’s try this by using cURL. If you are running Mac OS, cURL is already installed. Just run the Terminal app (Located under Applications->Utilities).

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

Alternatively you can use Postman if you are familiar with the tool as well to send this request.

For cURL the command should look as follows, which can also be adapted into Postman.

curl --location 'https://sms.8x8.com/api/v1/subaccounts/<subaccount>/surveys/<surveyId>/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: <apiKey>' \
--data '{
  "destination": "<mobileNumber>",
  "templateBody": "Hello {{firstName}}, your order is {{order_nr}}. {{url}} Please check and confirm if your scheduled delivery time is ok.",
  "templateVariables": {
    "firstName": "James",
    "order_nr": "ABC1000"
  },
  "source": "8x8"
}'

Remember to replace the , and values above. The {{url}} value does not need to be included in the templateVariables and will be automatically substituted by 8x8.

This should result in a SMS being sent similar to the one below with the URL replacing the {{url}} parameter's place in the SMS Body.

A successful request should return an 200 OK HTTP Response Code and the Response Body should appear as below:

{
    "umid": "<umid>",
    "clientMessageId": null,
    "destination": "<mobileNumber>",
    "encoding": "GSM7",
    "status": {
        "code": "QUEUED",
        "description": "SMS is accepted and queued for processing"
    }
}

Note that mobileNumber and umid's values will be replaced with your request's unique values.

Send Batch SMS Engage Survey

Now that we have covered how to send a Single SMS Engage Survey, there may also be times that it is appropriate to send multiple SMS Engage Surveys in a single API request. For those use cases, we can use the SMS Engage Batch API Endpoint.

In the following section, 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.

Request URL

• 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/batch
  • The {subAccountID} should be replaced by your own 8x8 Subaccount ID and the {surveyId} should be replaced by your Survey ID in a request.

Authentication

Use your API Key in the Authorization header of your HTTP request, this is denoted with the variable below.

curl --location 'https://sms.8x8.com/api/v1/subaccounts/<subaccount>/surveys/<surveyId>/messages/batch' \
--header 'Content-Type: application/json' \
--header 'Authorization: <apiKey>' \

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.

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

{
  "messages": [
    {
      "templateVariables": {
        "firstName": "Igor",
        "order_nr": "1010101",
        "age": 24
      },
      "destination": "<mobileNumber>"
    },
    {
      "templateVariables": {
        "firstName": "Petr",
        "order_nr": "1010104",
        "age": 20
      },
      "destination": "<mobileNumber>"
    },
    {
      "templateVariables": {
        "firstName": "Vasia",
        "order_nr": "1010102",
        "age": 22
      },
      "destination": "<mobileNumber>"
    }
  ],
  "template": {
    "source": "YourBrand",
    "templateBody": "Hello {{firstName}}, your order is {{order_nr}}. Please check and confirm if your scheduled delivery time is ok: {{url}}"
  },
  "clientBatchId": "MyBatch00001",
  "includeMessagesInResponse": true
}

The JSON parameters are explained in the table below:

Sending the API Request

Now that the API request is setup correctly you need, let’s try this by using cURL. If you are running Mac OS, cURL is already installed. Just run the Terminal app (Located under Applications->Utilities).

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

Alternatively you can use Postman if you are familiar with the tool as well to send this request.

For cURL the command should look as follows, which can also be adapted into Postman.

curl --location 'https://sms.8x8.com/api/v1/subaccounts/<subaccount>/surveys/<surveyId>/messages/batch' \
--header 'Content-Type: application/json' \
--header 'Authorization: <apiKey>' \
--data '{
  "messages": [
    {
      "templateVariables": {
        "firstName": "Igor",
        "order_nr": "1010101",
        "age": 24
      },
      "destination": "<mobileNumber>"
    },
    {
      "templateVariables": {
        "firstName": "Petr",
        "order_nr": "1010104",
        "age": 20
      },
      "destination": "<mobileNumber>"
    },
    {
      "templateVariables": {
        "firstName": "Vasia",
        "order_nr": "1010102",
        "age": 22
      },
      "destination": "<mobileNumber>"
    }
  ],
  "template": {
    "source": "YourBrand",
    "templateBody": "Hello {{firstName}}, your order is {{order_nr}}. Please check and confirm if your scheduled delivery time is ok: {{url}}"
  },
  "clientBatchId": "<batchId>",
  "includeMessagesInResponse": true
}'

Remember to replace the , , and values above. The {{url}} value does not need to be included in the templateVariables and will be automatically substituted by 8x8.

This should result in a SMS being sent similar to the one below with the URL replacing the {{url}} parameter's place in the SMS Body.

A successful request should return an 200 OK HTTP Response Code and the Response Body should appear as below.

{
    "batchId": "<batchUmid>",
    "clientBatchId": "<batchId>",
    "acceptedCount": 3,
    "rejectedCount": 0,
    "messages": [
        {
            "umid": "<umid>",
            "clientMessageId": "<batchId>/<mobileNumber>",
            "destination": "<mobileNumber>",
            "encoding": "GSM7",
            "status": {
                "code": "QUEUED",
                "description": "SMS is accepted and queued for processing"
            }
        },
        {
            "umid": "<umid>",
            "clientMessageId": "<batchId>/<mobileNumber>",
            "destination": "<mobileNumber>",
            "encoding": "GSM7",
            "status": {
                "code": "QUEUED",
                "description": "SMS is accepted and queued for processing"
            }
        },
        {
            "umid": "<umid>",
            "clientMessageId": "<batchId>/<mobileNumber>",
            "destination": "<mobileNumber>",
            "encoding": "GSM7",
            "status": {
                "code": "QUEUED",
                "description": "SMS is accepted and queued for processing"
            }
        }
    ]
}

You should receive multiple messages in the messages array assuming you set includeMessagesInResponse as true in the request body. If it was set to false then the messages array will be null.

Note that the batchUmid, batchId, mobileNumber and umid's values will be replaced with your request's unique values.

Survey Appearance

The webpages for the surveys are built by the 8x8 team for each customer based on their inputs. A few example pages are included below as they would appear in a mobile browser. They can include both text box and multiple choice type of questions.

The web pages are only examples, a survey webpage will be built by 8x8 as part of onboarding to SMS Engage that can be customised in terms of appearance and questions. please contact your account manager or send an email to 8x8 Support.

Reports

Reports related to SMS engage, you can check the Reports section of the Connect Dashboard.

For a given time period, reports will include the following information

For each survey response, clicking View response in the associated row will bring up the actual responses from the customer.

The Export button on the same page will give you the option to email a CSV file of the responses in the survey.