How to integrate

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

See here for more about Interactions in Engage.

Every Interaction in Engage is defined by a schema. Here is the structure of the schema used for the TestFreaks integration:

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

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

POST api/v2/interactionschemas

TestFreaks 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:

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").

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

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

This is sent to this endpoint:

POST api/v2/contacts/{contactId}

Or for API v3:

PATCH api/v3/contacts/{contactId}

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:

{
  "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. "
  }
}

This payload is sent to the interactions endpoint:

POST api/v2/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:

{
  "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.

Set up the custom trigger according to the instructions here.