This article describes the flows related to creating a 2-way SMS survey where Customer Insight Surveys can be sent to customers and they have the ability to respond via SMS to the questions in the survey.

Overview

This document describes the functionality and flow of a 2-way SMS survey.

The pre-requisites are to have:

• SMS service configured
• a survey created in our web interface

The flow is as follows:

1. Begins by calling the SendSurvey method in the consumer API
2. This triggers a SMS to the end-user with the first survey question
3. The 2-way SMS handler will process incoming responses from the end-user
4. The 2-way SMS handler will send the correct responses back until the survey is completed.

Flow when initiating a 2-way SMS survey

1. Invoke the SendSurvey method in the consumer API

Example code using rest tag and json body:   

<assignlocal variable="surveyId" value="2b156ca0-7562-4f2e-b851-e51f0bc27647"/>
<!-- Define survey_expiry if you want it to not be the default 3 days -->
<!-- <assignlocal notexpression="§exist{survey_expiry}" variable="survey_expiry" value="$dateadd(system_datetime,day,3)" /> -->
<include src="/Common/CustomerInsight/SendSurvey.xml"/>

Here is an example of the request payload sent through SendSurvey.xml:

{
  "clientReference": "$(system_session_id)",
  "expiryTime": "§{survey_expiry}",
  "userSessionVariables": [
    {
      "key": "agentid",
      "value": "$(system_last_user_id)"
    },
    {
      "key": "queueKey",
      "value": "$(system_queue_key)"
    },
    {
      "key": "consumerChannel",
      "value": "Phone"
    },
    {
      "key": "consumerSession",
      "value": "$(system_session_id)"
    },
    {
      "key": "consumerPhone",
      "value": "$(e164_phone_number)"
    },
    {
      "key": "systemCountry",
      "value": "$(system_country)"
    },
  ],
  "identifier": "$(e164_phone_number)",
  "identifierType": "Phone",
  "channel": "SMS",
  "content": "On a scale from 1-10 how much did you enjoy the shopping experience with us. Please respond by replying to this message."
}

The userSessionVariables can contain any key/value information which can later be used in reporting and visualisation of the results.   

All keys are optional.  

Relevant properties:

2. Get first question element

The API will loop through all survey elements in sequence until it finds an element that requires user input (ie some sort of question, scale, etc).

3. Send SMS

If more than 1 element is found, send one SMS per survey element with a 2 second delay. In cases where the survey has been configured with text elements before the first question, these will be sent first.

If the SendSurvey request containts any Content, the content will be pre-pended to the text in the first SMS.

Convert the element into sms text based on the element type.

For Norwegian numbers, subnumbering (sms session) will be used to ease identifying a specific user session.

4. Store user session

Store the user session with currentElementId = <id of the question element sent to end-user>

Flow when handling end-user responses

1. Find user session

Find relevant end-user session either based on SMS session (for Norwegian numbers) or based on end-user’s phone number.

If a user session is not found, send a generic survey not found SMS.

2. Survey completion check

If user session.currentElement is the completion element (ie user has already completed the survey), send the text defined for Survey Unavailable.

3. Special handling of dropdown and multiple choice responses

If the currentElement is of type drop-down list or multiple choice, subtract 1 from the response.
_{(This is because the responses of these element types are stored with the item number with a starting point of 0, whilst the sms text will number the first item as number 1 when asking for user response as that’s deemed a better user experience).}

4. Validate the response

Check if user response if of valid data type and within the defined range if a scale is used.

If validation fails, re-send the last question with a pre-pended error text.

5. Register user response

Store the user response in the database.

6. Find next question element

• Check if the currentElement is part of a rule condition, and if it matches the condition criteria, the rule action will determine the next element to send.

• If currentElement does not match any rules, find the next element in the survey sequence

• If no further elements are found, send the text defined in the Survey Completion element

7. Send SMS

Convert the survey element to a sms text based on the element type and send to the end-user.

8. Update user session

Update user session with the new elementId sent to the end-user to keep track of progress.