Send invitations with Business Generated Links

This feature is part of the Privacy add-on module, which can be purchased in addition to the Enterprise plan.

This guide is for developers who want to create Business Generated Links. Here you can learn how to generate encrypted links using your chosen programming language.

IMPORTANT

The Business Generated Links invitation method is only available to new Trustpilot Business customers in specific industries.

Trustpilot has created resources about Authenticated Encryption on Github to help you get started. Read about them here.

Guide for all programming languages

Business Generated Links use Authenticated Encryption with Associated Data (AEAD) and an approach called Encrypt then MAC (EtM). Trustpilot uses one key to encrypt the payload (encryptkey) and another key for the MAC part (authkey) to ensure data integrity.

In Trustpilot Business, go to Get reviews > Invitation methods > Business Generated Links to find the two keys.

Create Business Generated Links

  1. The keys copied from Trustpilot Business are displayed in a base64-encoded format. So, the first thing your application needs to do is a base64-decode of the keys.
  2. Create the JSON formatted payload object and insert the customer information. The following fields are required: email, name, and ref (reference number). Here’s an example: 
    {
    "email":"xyz@domain.com",
    "name":"John Smith",
    "ref":"1234",
    "skus":["sku1","sku2","sku3"],
    "tags":["tag1","tag2","tag3"]
    }

    Tags must not contain any spaces.

  3. Ensure the payload cannot be read by third-parties by encrypting the payload. Encrypt with AES-CBC using a key size of 256 bits, a block size of 128 bits, and PKCS7 padding mode
    • Generate an Initialization Vector (IV) according to the block size ( 128 bits)
    • Encrypt the JSON with the encryptkey and IV
    • Create a signature of the ciphertext.
    • For this, we use HMAC-SHA256 and the authkey. Compute the HMAC by hashing the IV followed by the ciphertext. Here's an example: HMAC = HMAC-SHA256( IV + ciphertext )
  4. Now base64-encode the IV + ciphertext + HMAC. Like this: base64_payload = base64( IV + ciphertext + HMAC )
  5. Finally, because base64 includes the slash (/) and plus (+) characters, it's necessary to URL-encode the payload above before adding it to the final link.
  6. The final link should look like this: 
      payload = urlencode( base64_payload )
  https://www.trustpilot.com/evaluate-bgl/<domain>?p=<payload>
  7. Replace the domain with your domain name and the payload with the payload you generated in step 5.

The following flowchart shows the necessary steps involved in correctly formatting, encrypting, and preparing the payload data prior to distribution:

Flow chart outlining steps for Business Generated Links

How to verify a Business Generated Link

There are two ways to verify that a Business Generated Link has been created correctly:

Test your link in a browser

Paste your link into a browser and search. Then create a test review. Select a star rating, add a title, and a review text. If the Submit review button is active, your encryption process succeeded. If you are asked to log in using Facebook, Google, or Email, then your encryption process failed. Remember not to post your test review.

Here's an example of a successful encryption process to the left and an unsuccessful one to the right:

Example of a successful encryption link to the left and a broken link to the right

Test your link with our command line interface (CLI)

You can install our command line interface (CLI) on your development computer. If you can decrypt your payload with the CLI, then you've encrypted your payload correctly.

Avoid using generic test email addresses (like test@gmail.com). Use a unique email address when testing the functionality.

Encode Business Generated Links for product reviews

To collect product reviews with Business Generated Links, add product SKUs to your payload. Here’s an example of a payload that includes product SKUs. It’s a simple JSON array:

{
  "email":"xyz@domain.com",
  "name":"John Smith",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"]
}

How do I localize a Business Generated Link for a specific country?

To localize the link, remove the "www." and replace it with the appropriate country code. For example:

https://de.trustpilot.com/evaluate-bgl/?p= https://es.trustpilot.com/evaluate-bgl/?p=

Send location review invitations with Business Generated Links

If you want to use Business Generated Links to send location review invitations, you need to include the location field when you add customer information to the payload object. Use the location ID you’ve given that specific location.

Here’s an example:

{
  "email":"xyz@domain.com",
  "name":"John Smith",
  "ref":"1234",
  "locationId": "id1",
  "skus":["sku1","sku2","sku3"],
  "tags":["tag1","tag2","tag3"]
}

The location ID is case sensitive.

Related articles