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:

Generate JSON payload string like mentioned above
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
Generate a random Initialization Vector (IV) with 16 Bytes length
Encrypt the JSON string using the generated key and IV with AES (256-bit key size, CBC mode)
Base64 encode that encrypted string (if not already done in step 4)
Concatenate the Salt and IV values and Base64 encode that string as well
Build a final token by concatenating the Base64 encoded Salt-and-IV string and the Base64 encoded encrypted string using: as delimiter/separator
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.