On this page


Overview

An ‘event’ in Ometria is any action taken by a contact which can be used to either segment or trigger a campaign. E.g. Placing an order, visiting your website, etc. 

Ometria has a number of in-built events, but custom events allow you to define your own automation campaign trigger, for example: 

  • wish list event
  • customer visited an offline store
  • customer has visited a specific webpage or has completed a specific action on a website.

These events will also be made available for you to use in your email templates.

Custom events are passed to Ometria via an API call.  You can find details of the API endpoint and the object definition in our API Reference.


Note: Custom events are only available for triggering automation campaigns - you can’t use custom events to segment contacts or add conditions in the customer filter. 


Setup

If you’re interested in implementing a custom event for your automation campaigns, please speak with your customer success manager to discuss your use case. 

We require the following information from you:

  • The event type you would like to use, e.g. wish list event.
  • Any top-level properties you would like to be able to segment on in the automation flow.
  • Any values in the properties object which represent a product ID. This can then be used to pull in the information which Ometria holds on this product (eg. title, price, image).

Ometria will:

  • Create the custom event and associated fields in the platform
  • Enable the custom event in the automation campaigns builder.

Your developers will need to set up the API call and test it.

You are responsible for all of the logic for your custom event - you will need to send us the event data and information. 


Note: You only need to supply data which you consider relevant for a specific custom event, as we will use product IDs to find the product details.

For example, if the custom event is to trigger an email when a contact visits a specific webpage, you must track this contact and send us the event when it happens - this will not be set up in Ometria.


Properties

Properties are the custom fields within a custom event, defined by you.

All properties in the request are made available for use in email templates. For example, {{ event.special_discount }} which will pull up the discount for anyone that has visited that specific page.

Note: Fields within a custom event triggered campaign only populate with the data you supply in your API call. A custom event campaign cannot use data held in the Ometria platform.

If you trigger a campaign without a value assigned to these fields then there will be blank areas in your email content. 

Fields

The following field types are available for custom events:

FieldDescription

String

Any characters permitted, including accents and other character symbols.

Integer

Only whole numbers, e.g. 1, 2, 3, 4, 500, -344

Decimal

Any numbers, e.g. 5, 5.6, 553.3433, -454.34343

Date

Date and time, e.g. 2018-01-05 15:03:04

Timestamps

The timestamp in a custom event is used by Ometria to trigger when the custom event is added to an automation flow.

You can use timestamps in the following ways:

  • A timestamp in the past will not enter the contact into the automation flow.
  • A timestamp set to the current time and date enters the contact into the automation flow immediately.
  • A timestamp set in the future will enter the contact into the automation flow when that time and date occurs.

Note: Automation flows can have 1000 contacts in at any one time. If your custom event will enter more than 1000 contacts with the same timestamp, then batch the timestamps in increments of approximately 5 minutes and send 1000 per increment.


Templates

You can use your existing automation templates with custom events or the Ometria team can create new templates if required, please ask your CSM for details.

If you are creating your own templates, the merge tag format for custom events is {{ event.property }}



Technical information

Custom Event Methods

Return a list of custom events

Trigger a Custom Event

Return a List of Custom Events By Type

Return a Specific Custom Event

Custom Event Objects

Custom Event Object


Returns a list of custom events

Path

GET /custom-events/

Description

Returns a list of custom events

Request Parameters

limit Number of items to return. Max 250.
typestring (default: "10")
inquery
offset

Index of first record.

typestring (default: "0")
inquery

Response

200 OK
CustomEvent 

List of custom event objects


403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)

[
  {
    "@type": "custom_event",
    "event_type": "whatever",
    "id": "xxxxxx",
    "identity_account_id": "",
    "identity_email": "",
    "profile_id": "xxxxx",
    "properties": {
    },
    "timestamp": "2017-05-01T14:00:00Z"
  }
]

Triggers a custom event

Path

POST /custom-events/

Description

Triggers a custom event in the Ometria platform.

Request Body

CustomEvent 

Custom Event object

Request Example

{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}

Response

200 OK

Custom Event successfully received

403 Forbidden

API key is not authorised to access this resource


Returns a list of custom events of a specific type

Path

GET /custom-events/{event_type}

Description

Returns a list of custom events of a specific type

Request Parameters

event_type

The event type

typestring
inpath
limitNumber of items to return. Max 250.
typestring (default: "10")
inquery
offset

Index of first record.

typestring (default: "0")
inquery

Response

200 OK
CustomEvent

List of custom event objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)

[
  {
    "@type": "custom_event",
    "event_type": "whatever",
    "id": "xxxxxx",
    "identity_account_id": "",
    "identity_email": "",
    "profile_id": "xxxxx",
    "properties": {
    },
    "timestamp": "2017-05-01T14:00:00Z"
  }
]

Returns a specific custom event

Path

GET /custom-events/{event_type}/{event_id}

Description

Returns a specific custom event

Request Parameters

event_type

The event type

typestring
inpath
event_id

The event ID

typestring
inpath

Response

200 OK
CustomEvent

A single custom event object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

The specific custom event could not be found

Response Example (200 OK)

{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}

CustomEvent: object

Describes a custom event. One of "profile_id", "identity_email", "identity_account_id" is required.

ValueTypeDescriptionRequired
@typestring

The value must be "custom_event". This shows that this record represents a custom_event object.

Required
idstring

The id of the custom event

Required
event_typestring

The type of the custom event

Required
timestampstring

The timestamp of the event following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

Required
propertiesobject

Properties to be used in the event. User defined.

Required
profile_idstring

The profile ID of the contact on which to trigger this custom event.

One Of These Values Is Required
identity_emailstring

The email of the contact record on which to trigger this custom event.

identity_account_idstring

The contact id of the contact record on which to trigger this custom event


Example

{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}