Skip to main content

Interactions

Caution

This functionality is part of a Beta release and is currently being tested. Any part of the feature could change before the full release.

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. Use cases with code samples can be found below.

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

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.

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

    Fetches all interactions of a specific schema for a contact using contactId and schemaId.

    Alternatively, fetches a specific interaction using interactionId as the only parameter.

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

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.

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: