Real Time Survey Token Creation

1. Prerequisites

1.1 You will need:

• Windows 10 laptop or MacBook. Current document follows Windows 10.
• Visual Studio 2019 Community Edition - Free ( download )
• Experience Management account with a running survey set-up
• Postman app ( download )

1.2 Setting it up:

• Install Visual Studio, Postman ( Takes: 30-60 minutes )
• Create a fresh clean development directory ( C:\Dev )
• Vendors API details (For use-case 2 only)

1.3 Understanding about WXM APIs:

The whole postman collection of WXM APIs can be imported from this link Primarily we would be using these two APIs mentioned below.

• Login Token API
• Survey Token API

Understanding various use cases for creating survey tokens real-time

Businesses have various internal systems that houses data. Systems such as CRM systems, Helpdesk tools, POS systems, Marketing automation tools, Loyalty program management tools etc are in play in every organization. Reaching out to customers with a survey as soon as a transaction is completed by them yields the highest response rates.

Let’s go through these use cases to explain the scenario.

Use case 1: Create survey token real time

• Post ticket closure send surveys to customers to capture Agent satisfaction metric
• Collect customer feedback over a web survey (ex. on your own website)
• Collect customer feedback over a email (ex. after a hotel checkout or service interaction)
• Trackable surveys by individual responders using single-use tokens per customer over API to get a unique URL per customer

CRM systems such as Salesforce or Microsoft Dynamics has case management (ticketing) capabilities. Even helpdesk tools such as Freshdesk or Zendesk are pretty popular for ticketing. Let’s consider a scenario where the business wants to reach out to their customers for a post ticket closure surveys to measure the agent satisfaction metric as soon as a ticket is closed.

The following steps are to be followed to build this simple integration using the open API’s provided by Experience Management.

(a) Try out using Postman

• Step 1: Import postman collection of WXM APIs from this link

  

• Step 2: Provide the username and password of your experience management account in Postman LoginToken Request and click on “Send”. At this step, you would obtain “bearer token” which comes in the response under “access_token” field.

  
  

  This is how a successful response would look like

  
  

• Step 3: Once the bearer token is generated successfully, Open “Survey Token API”(POST /api/SurveyToken) request and fill up the required parameters

  	
  {
  	"user": "<WXM username>",
  	"note": "Created using the API from Postman",
  	"validTill": "2020-08-20T06:25:35.749Z",  // Expiry time to be passed in UTC time format.
  	"validUses": 1,                           // No of times survey can be submitted
  	"location": "<WXM Questionnaire ID>",
  }
  	

  Complete model for Survey Token can be accessed here

• Step 4: Survey Token created without contextual prefills(Step 3 above) are good for anonymous surveys. However, for unique survey links per customer, prefills should also be passed while creating token. Open “Survey Token with Prefills API”(POST /api/SurveyToken) request and fill up the required parameters

  	
  {
  	"user": "<WXM username>",
  	"note": "Created using the API from Postman",
  	"validTill": "2020-08-20T06:25:35.749Z",   // Expiry time to be passed in UTC time format.
  	"validUses": 1,                            // No of times survey can be submitted
  	"location": "<WXM Questionnaire ID>",
  	"preFill": [
      {
        "questionId": "53d10eea3ec2411e8c1baa36",
        "questionText": "Customer ID",
        "textInput": null,
        "numberInput": 2345
      },
      {
        "questionId": "53d10eea3ec2411e8c112gb45",
        "questionText": "Customer Name",
        "textInput": "John Doe",
        "numberInput": 0
      }
    ]
  }
  	

  Here, questionId and questionText will be retrieved from WXM questionnaire. Only one value of textInput or numberInput is required to be passed by system where this is integrated, depending upon whether the prefill question is created as text type or number type.

• Step 5: The survey token response would contain a field as “id” which is the created survey token.

  {
      "id": "KN-137504",
      "user": "wxmuser",
      "created": "2020-08-13T10:55:30.768147Z",
      "note": "Created using the API from Postman",
  	  "preFill": null
  }

• Step 6: The survey token should be appended to this URL(https://nps.bz/) to generate survey URL which can be sent to customers over email/SMS or can be opened up in webview.

  Survey URL Example: https://nps.bz/KN-137504

(b) Integrate programmatically using reference implementation example

This reference example is implemented using .Net Core. You can choose to implement this in any other preferred language you want.

• Step 1: You can download or clone the code using this link. Once cloned, go to the solution directory “WXM Code Samples”->"WXMAPIExample”.

• Step 2: Launch “WXMAPIExample.sln” in Visual studio and expand “SurveyTokenCreation” project. We will be referring the implementation under this project only.

  

  
  

• Step 3: Generic survey properties are kept as configurable parameters in “appsettings.json”. Enter your Experience Management credentials and also change the questionniare ID and survey properties as per your requirements.

  
  

• Step 4: Now you can refer the implementation in “SurveyTokenCreation.cs” under “CreateToken” function

  
  URI for Survey Token creation API is "/api/surveytoken”. Base URL is configured in appsettings.json which is “https://api.getcloudcherry.com”.

  So, Survey Token API request URL is “https://api.getcloudcherry.com/api/surveytoken".

• Step 5: To pass the contextual prefills while creating a token, you should create an object with questionId, questionText and textInput or numberInput depending upon the type of the questions. All the questions (customer facing or prefills) created in Experience Management Questionnaire are either Number type or Text type.

  Values(textInput or numberInput) for each prefills should be passed dynamically. Currently for two sample prefills, dummy values are used.

• Step 6: The survey token(returned from “CreateToken” method) should be appended to this URL(https://nps.bz/) to generate survey URL which can be sent to customers over email/SMS or can be opened up in webview.

  Survey URL Example: https://nps.bz/KN-137504

Use case 2: Create survey token and dispatch through SMS/Email channel in real time using your preferred vendor

POS systems records all the sales that happens in a store. Let’s consider a retail business that has multiple stores and uses a POS system to record sales. After each sale, an email or SMS has to be sent to the customer with a survey link in it to measure post transaction NPS.

The following steps are to be followed to build this simple integration using the open API’s provided by Experience Management.

(a) Try out using Postman

• Step 1: Import postman collection of WXM APIs from this link

  

• Step 2: Provide the username and password of your experience management account in Postman LoginToken Request and click on “Send”. At this step, you would obtain “bearer token” which comes in the response under “access_token” field.

  
  

  This is how a successful response would look like

  
  

• Step 3: Once the bearer token is generated successfully, Open “Request Invitations for Email” API for Email and “Request Invitations for SMS” for SMS. Prefilling of data can be done using the same API.

  • Request Body to Send Email

  {
    "customerPhone": "8147338292",
    "customerName": "<Customer Name>",
    "subject": "<Mention Email Subject Here>",
    "customerEmail": "<Mention Customer Email Id>",
    "preFillByQuestionTag": {
      "email": "<Mention Customer Email Id>"
    },
    "template": "<Publicly accessed URL where Email template is hosted>",
    "tokenDetails": {
      "id": "",
      "user": "<Experience Management User>",
      "note": "This is a test survey token",
      "preFill": [
        {
          "questionId": "5dba93383b518609807f8eb0",
          "questionText": "Touchpoint",
          "textInput": "New Onboarding",
          "numberInput": 0
        },
        {
          "questionId": "5db68b06c76a0119487d8607",
          "questionText": "Email",
          "textInput": "EmailID of Customer",
          "numberInput": 0
        },
        {
          "questionId": "5dc5a1792dca541f7ceb7bd4",
          "questionText": "Policy Number",
          "textInput": "Policy Number",
          "numberInput": 0
        }
      ],
      "location": "<Experience Management Questionnaire ID>",
      "validUses": 1,                         // No of times survey can be submitted 
      "validTill": "2020-12-10T07:32:11.912Z" // Expiry time to be passed in UTC time format.                         
    },
    "isSMS": false,                           // For email, this field should be false
    "nonRepeatByUniquieQuestionTag": "email", // Throttling to be done on this question tag
    "nonRepeatWithinLastDays": 1,             // If sent in last <x> days, dont send the survey again
    "preFillByQuestionId": "<QuestionID for email question>"
  }

  • API Response

    Success case:

  	{
  		"message": "NPS By Email Requested : <Customer Email ID>"
  	}

  Failure cases(few are mentioned below):

  	{
  		"message": "Could not be sent"
  	}
  	
  	{
  		"message": "Skipped not to repeat for last 1 days"
  	}
  	
  	{
  		"message": "NPS By Email Requested : <Customer Email ID>Message from vendor: <Vendor API response>"
  	}

  • Request Body to Send SMS

  {
    "customerPhone": "<Mobile number of Customer>",
    "customerName": "<Customer Name>",
    "preFillByQuestionTag": {
      "mobile": "<Mobile number of Customer>"
    },
    "template": "",  // SMS Vendor GET API along with SMS template. Check "Note" below for more details
    "tokenDetails": {
      "id": "",
      "user": "<Experience Management User>",
      "note": "This is a test survey token",
      "preFill": [
        {
          "questionId": "5dba93383b518609807f8eb0",
          "questionText": "Touchpoint",
          "textInput": "New Onboarding",
          "numberInput": 0
        },
        {
          "questionId": "5db68b06c76a0119487d8607",
          "questionText": "Mobile ID",
          "textInput": "Mobile number of customer",
          "numberInput": 0
        },
        {
          "questionId": "5dc5a1792dca541f7ceb7bd4",
          "questionText": "Policy Number",
          "textInput": "Policy Number",
          "numberInput": 0
        }
      ],
      "location": "<Experience Management Questionnaire ID>", 
      "validUses": 1,                            // No of times survey can be submitted 
      "validTill": "2020-12-10T07:32:11.912Z"    // Expiry time to be passed in UTC time format.
    },
    "isSMS": true,
    "nonRepeatByUniquieQuestionTag": "mobile",   // Throttling to be done on this question tag
    "nonRepeatWithinLastDays": 1,                // If sent in last <x> days, dont send the survey again
    "preFillByQuestionId": "5db68b1f19f4dc32885f7a92"
  }
  	

  • API Response

    Success case:

  	{
  		"message": "SMS Requested : <Customer Mobile>Message from vendor: <Vendor API response>"
  	}

  Failure cases(few are mentioned below):

  	{
  		"message": "Could not be sent"
  	}
  	
  	{
  		"message": "Skipped not to repeat for last <x> days"
  	}
  	
  	{
  		"message": "SMS Requested : <Customer Mobile>Message from vendor: <Vendor API response>"
  	}
  	

  Complete model for Request Invitation API can be accessed here

(b) Integrate programmatically using reference implementation example

This reference example is implemented using .Net Core. You can choose to implement this in any other preferred language you want.

• Step 1: You can download or clone the code using this link. Once cloned, go to the solution directory “WXM Code Samples”->"WXMAPIExample”.

• Step 2: Launch “WXMAPIExample.sln” in Visual studio and expand “CreateSurveyTokenAndSend” project. We will be referring the implementation under this project only.

  

  
  

• Step 3: Generic survey properties are kept as configurable parameters in “appsettings.json”. Enter your Experience Management credentials and also change the questionniare ID and survey properties as per your requirements.

  
  

• Step 4: Now you can refer the implementation in “TokenCreationAndSend.cs” under “CreateTokenAndSendSurvey” method

  

  URI for Request Invitation API is "/api/RequestInvitation”. Base URL is configured in appsettings.json which is “https://api.getcloudcherry.com”.

  So, Survey Token API request URL is “https://api.getcloudcherry.com/api/RequestInvitation".

• Step 5: To pass the contextual prefills while creating a token, you should create an object with questionId, questionText and textInput or numberInput depending upon the type of the questions. All the questions (customer facing or prefills) created in Experience Management Questionnaire are either Number type or Text type.

  Values(textInput or numberInput) for each prefills should be passed dynamically. Currently for three sample prefills shown below, dummy values are used.

• Step 6: Finally, the CreateTokenAndSendSurvey method would be invoked and it will return the response recevied from the RequestInvitation API. For the success scenarios, Email/SMS will be dispatched using the vendor APIs and for failure scenarious, it will display the error messages received from Vendor APIs.