Page Comparison

...

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:

...

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

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:

Code Block

language	json

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

Full example of a JSON object used as payload:

...

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

Expand

title	Example using PHP

Code Block

language	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.

...

Versions Compared

Old Version 8

New Version Current

Key

Requirements

Example using PHP

Invitation link