Questionnaire Invitation Link [Encrypted]

This version of the Invitation link is GPDR compliant

Reach out to our Customer Support team to provide you with the Customer Alliance Review Subject (hash) and Auth key (key).


This document provides information on how to build a custom questionnaire invitation link. This invitation link can then be used outside of the Customer Alliance application for guest invitations, for example in your PMS or CMS. 

Requirements

To build a custom link you need the following:

  • Customer Alliance Review Subject (hash)

  • Ability to generate an AES encrypted JSON token

  • Auth key for encrypting that token

 

The content of the encrypted token is a stringified JSON object with the following properties:

Name

Mandatory

Details

Name

Mandatory

Details

email

yes

The email for the survey responder

departure_date

yes

  • format Y-m-d. Example: 2022-09-30

  • at most 180 days in the past and 365 days into the future

language

yes

The two character code specified by https://en.wikipedia.org/wiki/ISO_639-1

name

no

The guest’s last name

reservation_id

no

The unique reservation id (string)

attributes

no

A JSON object for key/value pairs. For the values we only support “scalar values” like integer, float, string. We also only allow a maximum of 255 characters per attribute value and a maximum of 25 attributes in total.

Those attributes will be stored with the review and can be retrieved via API or also be accessed from the platform’s review stream.

Example:

{ "room_number": 400, "room_category": "double room", "whatever_other_attribute": "some_value" }

 

Full example of a JSON object used as payload:

{ "email": "some@email.com", "departure_date": "2022-09-23", "language": "de", "name": "Test", "reservation_id": "123456", "attributes": { "room_number": "some value", "room_category": "some value", "other_attribute_1": "some value", "other_attribute_2": "some value" } }

 

Now this JSON payload string needs to be encrypted. For this, we are using AES with a 256-bit key size and CBC mode.

Steps for creating the encrypted token:

  1. Generate JSON payload string like mentioned above

  2. Generate encryption key using PBKDF2 with the Auth key/password provided by us with

    1. 256 Bit key length

    2. random Salt value with 8 Bytes length

    3. 1000 iterations

    4. SHA1 digest

  3. Generate a random Initialization Vector (IV) with 16 Bytes length

  4. Encrypt the JSON string using the generated key and IV with AES (256-bit key size, CBC mode)

  5. Base64 encode that encrypted string (if not already done in step 4)

  6. Concatenate the Salt and IV values and Base64 encode that string as well

  7. Build a final token by concatenating the Base64 encoded Salt-and-IV string and the Base64 encoded encrypted string using: as delimiter/separator

  8. Url-encode this final token so it can be passed to our URL as a query parameter

Example using PHP

<?php declare(strict_types=1); // those two parameters are provided by us $reviewSubjectHash = 'someNiceHash'; $authKey = 'someNiceAuthKey'; // next we need to build the JSON payload string $jsonPayloadString = json_encode( [ 'email' => 'some@email.com', 'departure_date' => '2022-11-17', 'language' => 'de', 'name' => 'Test', 'reservation_id' => '123456', 'attributes' => [ 'room_number' => 'some value', 'room_category' => 'some value', 'other_attribute_1' => 'some value', 'other_attribute_2' => 'some value', ], ], JSON_THROW_ON_ERROR, ); // generate random Salt with 8 bytes length $randomSalt = openssl_random_pseudo_bytes(8); // generate encryption key using Auth key provided by us and random salt value $encryptionKey = openssl_pbkdf2($authKey, $randomSalt, 256, 1000, 'sha1'); // generate random IV with 16 bytes length $randomIV = openssl_random_pseudo_bytes(16); // ecrypt json payload string // this will already return a Base64 encoded value $encryptedJsonPayload = openssl_encrypt($jsonPayloadString, 'aes-256-cbc', $encryptionKey, 0, $randomIV); // build final token that can be used inside URL // by prefixing Base64 encoded Salt-and-IV and separating the two Base64 encoded strings with ":" $urlEncodedToken = urlencode( sprintf('%s:%s', base64_encode($randomSalt.$randomIV), $encryptedJsonPayload) ); // build URL: $url = sprintf('https://go.customer-alliance.com/guest/redirect/poststay/%s?token=%s', $reviewSubjectHash, $urlEncodedToken); // if we assume we use "00000000" for the Salt and "0000000000000000" for the IV // then this would lead to the following url: // https://go.customer-alliance.com/guest/redirect/poststay/someNiceHash?token=MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw%3AJcGXHADkRta%2B2LlLRwJo2tHvpW7SHQB7XxPPEe85dM2q1zK%2FhX2b5dkdfhj%2Fu9ZpD7yezQLWPHIOVrS66ffxEHk1aeIYdPn4iKESwdO2CzlhAWViRfp85WJD7LkQGNlkyTK2J1YsnIa9kBKov0YMmus9PosijppjdvS3%2B9Yn3MLA5oivkz8ZEZ9jrSzd8vevmYE9%2BwKshSTNK8SZzQmxXw0CCPDPcWa1DDowofu8urJIUZrsT4R7jrKwgL4HjOzKwX8ckmQ%2BQNFpBm6FX%2FauEH7rlr92wefemwoxyTS5pcFa2agrNXglcyOEGw6AZ77qyKpA8ydN8jwReZy1Cs07dQ%3D%3D

Invitation link

The link is constructed as follows.