Event

Last Updated: Monday, August 15, 2022

Overview

Events are individual occurrences to be routed to appropriate actions based on the event_type. Each event_type must be set up in Platform prior to the call for a successful receipt of SMS on mobile phone. See Event Triggered Messages.

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	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_id, mdn, 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_id, mdn, 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_id	String	Identifies the intended device of the triggered event message for push messages. Note: One of external_person_id, mdn, person_id, or 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_key/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.

The Event API will accept 300 requests/second. If you anticipate greater volume, consider using a message queue to send the requests so retries and throttling can be applied if necessary.

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.