Skip to main content

Interactions

Important

This function is available for Engage customers who are using the paid add-on component Loyalty and Retention.

An interaction in Engage is some happening or event that we want to save to a specific contact in Engage. For example, it could be when a contact:

  • Writes a review

  • Posts on Instagram

  • Refers a friend

  • Reuses or repairs something

  • Marks an item as a favourite

Interactions give us another way to collect data that we can use to understand and engage the consumer.

Note

Interactions are intended for events that can't be collected in other ways. Things like purchases, returns, NPS and so on that already have their own pathways into Engage should not use Interactions.

The basics

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

Volumes and performance

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.

The interactions API

Interactions use two dedicated endpoints.

The interactionschemas endpoint

This endpoint is used to define the interaction schemas your interactions can use:

  • GET api/v2/interactionschemas

    Fetches all the interaction schemas defined for this tenant.

  • POST api/v2/interactionschemas

    Posts an interaction schema to create a new kind of interaction.

  • DELETE api/v2/interactionschemas

    Deletes a specific interaction schema using its unique ID.

  • GET api/v2/interactionschemas/{interactionSchemaId}

    Fetches a specific interaction schema using its unique ID.

An UPDATE does not exist for this endpoint, meaning that once it's created, an interaction schema can't be altered. However, it is fine to delete an interaction schema and then submit a new one with the same ID. No data connected to a schema is deleted when the schema is deleted, just the schema itself.

Any automation triggers set up for a schema that has been deleted will result in errors/deadletters and automation flows that do not progress. But as soon as a schema with the same ID is put back in, the automation will work as before, provided the changes made are backward compatible (meaning that no existing properties in the schema have been removed in the updated version).

Caution

Interaction schemas can't be updated, but can be deleted and then recreated with the same identifier (ID). The new schema must be backward compatible with the deleted one.

The interactions endpoint

This endpoint concerns the individual interactions (interaction events) sent to Engage. Such an interaction is always linked to a specific contact and a specific interaction schema.

  • GET api/v2/interactions/{interactionId}

    Fetches a single interaction using its unique interactionId. Included in the response are the contactId and schemaId.

  • GET api/v2/interactions

    Fetches all interactions of a specific schema for a contact using the contactId and schemaId. If the contact has more than 50 interactions the response will contain an URL pointing to the next page of 50 interactions. You can also, in Swagger, send the continuation token from the response as the continuation parameter in a new request to get the next page of 50 interactions.

  • POST api/v2/interactions

    Sends a new interaction for a specific contact and interaction schema to Engage.

  • DELETE api/v2/interactions

    Deletes a specific interaction using its interaction ID.

The schema

An interaction, its data and identifier, are defined in a JSON schema. Read more about the formatting standards here. 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"
     },
     "created": {
       "type": "string",
       "format": "date-time",
       "displayName": "Created",
       "showInContactCard": "true"
     },
     "name": {
       "type": "string",
       "displayName": "Name",
       "showInContactCard": "true"
     }
   },
  "required":["name"]
 }
}

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

Caution

The ID field for an interaction schema can only contain the characters a-z, A-Z, 0-9, underscore (_) and dash (-). For example: Autumn-campaign_2023 is allowed, but Höst-kampanj_2023 is not.

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:

  • $schema has currently only the value shown

  • type should always be "object" as shown

  • properties are the properties that make up an interaction

  • required defines the properties that an interaction of this schema must contain

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

  • type (the property type) which can be "string", "number", "integer" or "boolean".

  • format is optional and defines which format the attribute must have. For example, the "created" attribute is of type "string" with a format of "date-time". So only strings in the format "2018-11-13T20:20:39+00:00" will be allowed. Read more here about the various formats.

  • displayName is what's shown in the Engage UI for this property.

  • sortOrder and showlnContactCard are display attributes for the contact card.

Note

You can set up rules for the interaction schema, such as define which fields are required.

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

POST api/v2/interactionschemas

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

Caution

Deeply nested JSON structures are not currently supported. Don't use more levels than shown in the examples.

Sending an interaction

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,
        "created": "2011-11-03T20:00:11",
        "name": "Reused Item"
    }
}

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

POST api/v2/interactions

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

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:

POST api/v2/interactions/{interactionId}

Product information in interactions (productSku)

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. 

In this section: