Surveys - Generating personalized links

Client hotel can send the link to the survey themselves.

The link has the following format:

https://survey.reviewpro.com/feedback/mail?<query-params>

Request Type: GET

Instead of survey.reviewpro.com client can use any host name, as long as all the request to that host name are forwarded to survey.reviewpro.com.

Parameters

Param Value Required
apiKey <your api key> Yes
surveyId  <id of the survey> Yes
pmsId id of the hotel in external id mapping section of account settings Yes
email guest email Yes
firstName guest's first name Yes
lastName guest's last name Yes
checkin guest checkin date in yyyy-MM-dd format. Interpreted as date string in UTC Yes
checkout guest checkout date in yyyy-MM-dd format. Interpreted as date string in UTC Yes
... any other extra guest data, each as separate parameter distinct from the mentioned above No
sig HMAC using a secret key and SHA256 message digest algorithm (only for non-encrypted links) Yes

Encryption of the link 

For security or privacy reasons you can decide to encrypt the link, to hide the parameters passed on in the URL. ReviewPro supports the secure Rijndael 256-encryption. To be able to encrypt links in a proper way for ReviewPro to be able to ‘read’ them you need the following:

  • Encryption key of 20 characters: this will be provided by ReviewPro, for this you can contact reviewpro.integrations@shijigroup.com.
  • Encryption secret of 24 characters: this will be provided by ReviewPro, for this you can contact reviewpro.integrations@shijigroup.com.
  • The base url: https://survey.reviewpro.com/feedback/mail
  • For the encryption, please use an IV of NULLs, a padding of 32 and CBC and make sure to urlencode plus base64encode the result of the encryption before adding it to the full link.

You would encrypt all parameters with guest-data that would typically go into a survey-link:

“?email=john.doe@example.com&checkin=2022-09-20&checkout=2022-09-25&firstName=John&language=en&lastName=Doe&pmsId=1234&room=123&roomType=suite&surveyId=2265e0a6bc5 d5639ea646fe0&view=desktop”

A typical encrypted link would look like: https://survey.reviewpro.com/feedback/mail?encryption=Rijndael&apiKey=<encryption-key>&key=<encrypted guest data>

Signature generation for non-encrypted links 

sig is a HMAC using a secret key and SHA256 message digest algorithm. It takes as an input all query parameters concatenated in the alphabetical order by key (where UPPERCASE goes before lowercase): apiKey, checkin, checkout, email, firstName, lastName, pmsId, surveyId, etc. The secret key can be obtained from your Mashery account settings. Please note that although the parameters will need to be URLENCODE in the final URL, they are not URLENCODE to calculate the sig.

Example

Assuming that the url has parameters:

  • apiKey = "23675469989xxhy0"
  • checkin = "2014-01-01"
  • checkout = "2014-01-02"
  • email = "aaa@bbb.com"
  • firstName = "John"
  • lastName = "Doe"
  • LoyaltyNumber = "23445"
  • pmsId = "53770"
  • surveyId = "UtjT-oSiRJoMGL-k"

The concatenated string (all the parameters in alphabetical order, where UPPERCASE goes before lowercase, the parameters overall and nps are never included in this string) to encode is:

2344523675469989xxhy02014-01-012014-01-02aaa@bbb.comJohnDoe53770UtjT-oSiRJoMGL-k

If you example shared key is "ABC", the sig will be:

fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

You can test HMAC + HA256 generation via online tools like http://www.freeformatter.com/hmac-generator.html.

The final URL with sig appended will read:

https://survey.reviewpro.com/feedback/mail?apiKey=23675469989xxhy0&checkin=2014-01-01&checkout=2014-01-02&email=aaa@bbb.com&firstName=John&lastName=Doe&pmsId=53770&surveyId=UtjT-oSiRJoMGL-k&LoyaltyNumber=23445&sig=fa5bd997dfadd787b6bc673233cbbc1ef6a4cb121332821b047ec36e90f1c639

Including NPS or Overall in invitation emails 

ReviewPro supports having either an NPS or Overall question directly in the invitation email to increase the response ratio. The chosen score from the email wll be prefilled in the survey when opening the survey in the webbrowser. The score of NPS or Overall are specific parameters which should be passed in the links in the invitation mail.

We have two types of urls, encrypted and not encrypted :  

  • Encrypted  

In this case the "nps" or "overall" must be explicitly in the url as in https://survey.reviewpro.com/feedback/mail?encryption=Rijndael&apiKey=<apiKey>&key=<key>&nps=2  

  • Not Encrypted  

In this case the "nps" or "overall" must be explicitly in the url, but the signature ("sig" param) must be generated WITHOUT this new param as in https://survey.reviewpro.com/feedback/mail?apiKey=<apiKey>&<...params>&nps=2&sig=<sig>  


The following Python script can be used to calculate sig. It accepts two parameters: api shared secret and the survey url without the sig parameter, and outputs sig to the console.

import hmac
import hashlib
from urlparse import urlparse, parse_qs
import sys

o = urlparse(sys.argv[2])
params = parse_qs(o.query)

s = ''.join(''.join(sorted(v)) for _, v in sorted(params.items()))

sig = hmac.new(sys.argv[1], msg=s, digestmod=hashlib.sha256).hexdigest()

print sig

Another example of sig generation in Java

String key = "whatever"
TreeMap<String, String> sortedParams = new TreeMap<>();
sortedParams.put("surveyId", "45fa3453g");

StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> param : sortedParams.entrySet()) {    
	sb.append(param.getValue());
}

 String algorithm = "HmacSHA256";
Charset charset = Charset.forName("UTF-8");
Mac hmac = Mac.getInstance(algorithm);
SecretKey secretKey = new SecretKeySpec(key.getBytes(charset), algorithm);
hmac.init(secretKey);
 
byte[] b = sb.toString().getBytes(charset);
String sig = Hex.encodeHexString(hmac.doFinal(b));

Testing

Parameters can be tested using the following url: 

https://survey.reviewpro.com/feedback/mail/testParams?<query-params>

Request Type: GET

It takes the same query parameters as the survey url.