Interactions

An Engage Interaction is a dynamic object, meaning that the data in an interaction does not need to be set by Voyado, but instead can be customized through a schema provided by the customer.

An Interaction is different from an Activity in Engage. Activities have only one data type, and are imported through XML, whereas interactions can be fully customized and use the API.

You can use the data collected through interactions in a number of ways:

Segmentation: Create segmentations based on the number of times or the time when an interaction was received in Engage.

Contact card: In the tab "Interactions" you can get an overview of which interactions a contact has received.

Automations: Set up an automation flow using the triggers "New Interaction" (triggered by any interaction being received for the first time) or "New specific interaction" (triggered by an interaction of a specific schema, with a specific value, being received for the first time).

Interactions are primarily meant for tracking of events connected to contacts and their interaction with the retailer. There should be a marketing or loyalty purpose with using Interactions, not just data transfer and/or storage. There are no exact limits defined on the amount or frequency of data but Voyado reserves the right to restrict data volume in cases of excessive use.

Interactions use two dedicated endpoints.

An interaction, its data and identifier, are defined in a JSON schema. Read more about the formatting standards at this page. Once the schema is created, it must then be posted to the API, after which interactions that follow that schema can be used.

Here is an example of a schema, a few other examples can be found below:

{
 "id": "Reuse-Spring-2023",
 "displayName": "Reuse Spring Sale",
 "jsonSchema": {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
     "price": {
       "type": "integer",
       "displayName": "Price",
       "showInContactCard": "true",
        "sortOrder": "1"
     },
     "purchase-timestamp": {
       "type": "string",
       "format": "date-time",
       "displayName": "Purchase timestamp",
       "showInContactCard": "true",
        "sortOrder": "2"
     },
     "name": {
       "type": "string",
       "displayName": "Name",
       "showInContactCard": "true",
        "sortOrder": "0"
     }
   },
  "required":["name"]
 }
}

id defines the alias (ID) for this kind of interaction and must be unique.

displayName is the string that will be displayed in the Engage UI for this kind of interaction.

jsonSchema is the actual schema definition.

Under jsonSchema we have the following:

Finally, each individual property inside properties is made up of the following:

The schema is then sent to this endpoint as the body of the request:

POST api/v3/interactionschemas

Now this new kind of interaction, as defined by this schema, is ready to use.

Once the schema has been accepted by Engage, you can start sending that kind of interaction. Every interaction must be linked to a specific Engage contact. This interaction uses the schema defined above:

{
    "contactId":"cf6d21fa-6e2b-481c-ab38-afa1012233ff",
    "schemaId": "Reuse-Spring-2023",
    "createdDate": "2023-05-23711:13:42.074Z",
    "payload":{
        "price": 100,
        "type": "Jeans",
        "name": "Reused Item"
    }
}

*createdDate is optional

This is sent as the body of a request to the following endpoint:

POST api/v3/interactions

If the createdDate is not specified in the payload, it will be set to the current timestamp.

If a property in the payload does not match the schema, that property will not be sent to Engage, but will still be saved in blob storage. If the interaction does not follow the rules of the schema, it will be ignored.

A unique ID for this interaction will be returned if it is accepted. This can be used to retrieve that specific interaction again, if that is ever needed, through the endpoint:

GET api/v3/interactions/{interactionId}

Many customer interactions are events where a product might be involved, for example, a product review or repair. Product metadata such as category, brand, dimensions etc. might be useful in these cases for personalisation in email communication or other purposes. Therefore you should always add all this data to the schema. 

However, it might be wise to also indicate exactly which product that is the subject of the interaction. For this, use the reserved property name productSku because Engage might later on develop functionality around this, automatically enriching the interaction product metadata. This is a string value.