> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trustvoice

Trustvoice is an online platform that allows businesses to collect customer reviews to compare and use them for sales and marketing. It aggregates both professional and user reviews from thousands of sources in many different languages Trustvoice can send reviews to Engage which can then be viewed in the Engage UI, used in segmentation or acted on using Engage automations.

The Trustvoice integration can be used for the following in Engage:

* Enriching a customer's profile (their contact card) with review data
* Enabling the Engage user to perform segmentation of their contact's reviews
* Triggering automations post-purchase to prompt users to leave a review (coming soon)

## Integrating Trustvoice

The Trustvoice integration in Engage involves *Interactions* and *custom contact attributes*. A custom automation trigger will be added in a later iteration.

<Warning>
  Contact your account manager at Voyado before activating this integration. If Trustvoice will be using delta share data, you as a customer will need help from Voyado to perform the setup.
</Warning>

The general steps in the integration are:

* Enable interactions (must be done in the Voyado backend)
* Create API keys that will be shared with Trustvoice
* Create custom attributes (explained below)
* Set up the custom trigger used to trigger review emails
* Set up Delta share (must be done in the Voyado backend)

### 1 - Enable interactions

Start by activating interactions for your Engage account (ask your Voyado PM to do this for you).

See more about interactions here:

<Card title="Learn about interactions" href="https://developer.voyado.com/docs/loyalty/interactions" icon="https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083" horizontal width="128" height="128" data-path="icons/developer-link.png" />

### 2 - Define the interaction schema

Every interaction in Engage is defined by a *schema*.

Here is the structure of the schema used for the Trustvoice integration:

```json theme={null}
{
   "jsonSchema":{
      "$schema":"https://json-schema.org/draft/2020-12/schema",
      "type":"object",
      "properties":{
         "productSku":{
            "type":"string",
            "displayName":"Sku",
            "showInContactCard":"true",
            "addToSegmentation":"true"
         },
         "rating":{
            "type":"integer",
            "displayName":"Rating",
            "showInContactCard":"true",
            "addToSegmentation":"true"
         },
         "comment":{
            "type":"string",
            "displayName":"Comment",
            "showInContactCard":"true"
         }
      }
   },
   "id":"completedProductRating",
   "displayName":"Completed Trustvoice review"
}
```

To create the Interaction, this schema is sent to the endpoint:

```http theme={null}
POST api/v3/interactionschemas
```

Trustvoice will set up the schema on their end.

### 3 - Create the custom attributes

Trustvoice uses some custom contact attributes in Engage to send review information. You'll need to set there attributes up first. Navigate to **Administration > Configure Engage** and then **Contact attributes**.

Now create the following three custom attributes:

| Id                 | Name                 | Type    | Description.                                     |
| :----------------- | :------------------- | :------ | :----------------------------------------------- |
| reviewLatest       | Review Latest        | Date    | The most recent date of a review                 |
| reviewLatestValue  | Review Latest Value  | Integer | The score / value of the contact's latest review |
| reviewAverageGrade | Review Average Grade | Number  | The contact's overall review rating              |

Make these attributes "Segmentable", "Exportable" and "Read-only in contact card".

You should also map these three custom attributes to a specific contact panel giving you an easy way to view them (for example, a tab on the contact card named "Rating and Review").

Make sure you pick the correct Type for the custom attributes.

Here is a payload sent from Trustvoice to Engage to update these attributes for a contact:

```json theme={null}
{
    "reviewAverageGrade":4.5,
    "reviewLatest":"2024-11-20T13:00:00.000Z",
    "reviewLatestValue":5,
    "interests":"sport"
}
```

This is sent to this endpoint:

```http theme={null}
POST api/v2/contacts/{contactId}
```

Or for API v3:

```http theme={null}
PATCH api/v3/contacts/{contactId}
```

### 4 - Send the interaction

Once the schema has been created and posted, you can send interactions of this type. In the case of the schema above, the interactions you send will look like this:

```json theme={null}
{
  "schemaId": "completedProductRating",
  "contactId": "ea50e150-e12a-49f9-a496-b21001450d55",
  "createdDate": "2022-07-05T09:26:01.000Z",
  "payload": {
    "productSku": "17184225",
    "rating": 5,
    "comment": "Ett bra grepp precis som jag förväntade mig. "
  }
}
```

The `schemaId` (in this case "completedProductRating") must match the one used in the schema definition payload.

This payload is sent to the interactions endpoint:

```http theme={null}
POST api/v3/interactions
```

The interaction can be picked up in Engage by a custom automation trigger and used to start an automation. An example of the response is:

```json theme={null}
{
  "id": "gvwixukdja3w5v6afac47pkoi27346i52wyeu37faaqik76cocyjv4ih2gj7zwyiojsxm2lfo5jwk3tu",
  "self": {
    "contactId": "6e48d16c-05c0-46bd-be1d-b06f0085c2b0",
    "href": "https://qaretail1.acceptanstest.voyado.com/api/v3/interactions/gvwixukdja3w5v6afac47pkoi27346i52wyeu37faaqik76cocyjv4ih2gj7zwyiojsxm2lfo5jwk3tu",
    "created": "2023-12-14T10:56:16+00:00"
  }
}
```

The interaction details can be viewed on the contact card, on the "Interactions" tab.

### 5 - Set up custom trigger

Set up the custom trigger according to the instructions here:

<Card title="See custom trigger setup in Config Hub" href="https://help.engage.voyado.com/hc/en-gb/articles/23407506807068-Custom-triggers" icon="https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/help-center-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=4e7f518f776580d7cdae461a964ea2dc" horizontal width="128" height="128" data-path="icons/help-center-link.png" />

1. Name the custom trigger “Trustvoice review”
2. Give it the `triggerId` of “sendReview”

Add the three fields to be used in the custom trigger's payload:

| **Name**   | **Description**        |
| :--------- | :--------------------- |
| reviewHTML | The products to review |
| type       | Type of send-out       |
| language   | Language in Trustvoice |

### 6. Request delta share

This will be setup by a CX engineer from the Voyado team. Contact your account manager to enable this functionality.

## Trustvoice FAQ

Here are some commonly asked questions regarding the Trustvoice integration:

<AccordionGroup>
  <Accordion title="Can Trustvoice collect and send custom fields such as favorite brand, golf handicap, etc.?">
    Yes, as long as they gather that information in the review process that can be stored in Engage as a custom attribute.
  </Accordion>

  <Accordion title="Can I filter on the ratings and reviews in Engage?">
    Yes, you are able to filter on rating and reviews.
  </Accordion>

  <Accordion title="Is Trustvoice a Google review partner?">
    Yes, at least for product reviews.
  </Accordion>

  <Accordion title="Who sets up the interactions schema?">
    Trustvoice sets up the schema.
  </Accordion>

  <Accordion title="Can Trustvoice migrate existing ratings and reviews to Engage at go-live?">
    Yes, that is possible to do.
  </Accordion>
</AccordionGroup>