Introduction

This documents describes Ometria Custom Events and provides examples of their use and guidance on how to create them.

Summary

Custom Events are Contact events that can trigger automated campaigns through actions not pre-configured by Ometria.

Custom Events can be used for various scenarios such as 

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

Custom Events are API triggered and provide the ability to send over custom data to populate fields within a template through the sending process. 

Contents

How to Setup A Custom Event

What You Will Need To Do

You will need to provide Ometria with the following for the Custom Event to be created:

  • Name of Custom Event

  • Properties to be included in the event and what data type:

    • String

    • Boolean

    • Number

    • Products List

  • Create the API call

  • Test the API call

What We Will Do

  • We will create the Custom Event with the associated fields
  • We will enable the Custom Event to be available within the Automation builder.

Properties

Properties are the custom fields within a Custom Event. Properties are defined by you and can be merged into the campaign’s template content.

Note: Fields within a Custom Event campaign only populate with the data you supply within 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 within the campaign.

Timestamps

The timestamp in a Custom Event is used by Ometria to trigger when a Custom Event is added to an automation flow.

You can use timestamps in a variety of different ways;

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

Note: Automation flows can have 1000 contacts in at any one time. If your Custom Event will post more than 1000 contacts with the same timestamp then batch the timestamps in increments of 5 minutes and send 1000 per 5 minute increment.

Template Creation

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

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