Skip to end of metadata
Go to start of metadata

Last Updated: Friday, January 3, 2020



Overview

Events are individual occurrences to be routed to appropriate actions based on the event_type. 

The event_id should be unique for association and debugging purposes. The event_id may be omitted, in which case the platform will generated a unique ID. Re-using an event_id may result in successive events failing.

What are Events Used for?

Typical uses of events include triggering push and SMS messages.


Please review the Event Triggered Messages scenario for an example of how to use an event in a real-world situation.

Generic Event Example

{
  "event_id": "2d4a2",
  "event_type": "day_of_delivery",
  "event_data": {
    "first_name": "Bob",
    "external_person_id": "abcd12345",
    "delivery_time": "5:00 PM",
    "order_url": "https://example.com/orders/12345"
  },
  "debug_data": {
    "field": "CUST_SYSTEM"
  }
}


Note: If you are using Version 1 of the APIs, you cannot use the E.164 MDN international format. If you do use it, you will get an error returned.

Elements

Field Name

Type

Max Char Length

Description

Required?

event_type

String


Used to identify a linked API triggered event in the Platform. Valid characters in the event_type field are alphanumeric, dash and underscore.

Note: event_type values are NOT case sensitive.

Yes
event_data

Object


A placeholder object that can contain any useful data relevant to the event. Any valid JSON can be provided within the object for later reference within the API triggered event in the Platform. These fields are carried through on the event and can be referenced by any of the actions to filter or personalize the action to the individual event.

Yes

event_data.external_person_id

String


Identifies the intended recipient of the triggered event message. See Person APIs for the field definition.

*Note: One of external_person_idmdn, person_id or vibes_device_id is required.

Yes*
event_data.mdn

String


Identifies the intended recipient of the triggered event message. See Person APIs for the field definition.

*Note: One of external_person_idmdn, person_id or vibes_device_id is required.

Yes*
event_data.person_id

String


Identifies the intended recipient of the triggered event message. Value can correspond to either a person_key OR a person_id  for this field. See Person APIs for the field definition.

*Note: One of external_person_id, mdn, person_id or vibes_device_id is required.

Yes*
event_data.vibes_device_idString

Identifies the intended device of the triggered event message for push messages. 

*Note: One of external_person_id, mdn, person_idor vibes_device_id is required.

Yes*
event_id

String


The event_id should be unique within the Mobile Database so that it can be uniquely tied to the action for associating and debugging purposes. The event_id can be supplied by the customer or omitted, in which case a unique ID will be generated by the Platform. The event_id is idempotent and re-using an event_id will lead to the event being ignored and no message sent. The event_id has a max length of 40 characters.

No
debug_data

Object


Similar to the event_data field in that it can contain any valid JSON information. This data is also carried through on the event, although the fields are not made available to the actions for filtering or personalization. This block is generally used to provide upstream system information to help customers diagnose how and when an event was generated.

No

Create Event

The following will submit a new event into the system.

POST /companies/:company_id/events


Notes:
An HTTP 202 - Accepted response will be returned if the event has been successfully submitted but will not necessarily result in a message.

Return JSON

{ "event_id": "ABCD-GUID-12352234234-ABCD"}

An abbreviated event JSON block will be returned upon successful submission. It will contain the event_id for the event.

  • No labels