Event API

On occasion, you may want to send messages—SMS, MMS, or push—to your customers that correspond to key events in their customer journey.

For example, say you’d like to send your customer a text message when their item is shipped. The first step in this process is to create a defined event that informs the Vibes system that the item has been shipped.

The easiest way to define an event_type is in the platform (see step one of this guide for more info).

📘

Use unique event_ids

The event_id should be unique for association and debugging purposes. If you plan on registering for event-triggered callbacks, we recommend providing an event_id, as this can make identifying the originated event easier in the future. If the event_id is be omitted, the platform will generate a unique ID. Re-using an event_id may result in successive events failing.

Available API Methods

Elements & Attributes

Field NameTypeDescriptionRequired?
event_typeStringUsed 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_dataObjectA 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_idStringIdentifies the intended recipient of the triggered event message. See Person APIs for more information on this field.

Note: One of the following is required:
external_person_id, mdn, person_key, person_id, or vibes_device_id.		Yes*
event_data.mdnStringIdentifies the intended recipient of the triggered event message. See Person APIs for more information on this field.

Note: One of the following is required:
external_person_id, mdn, person_key, person_id, or vibes_device_id		Yes*
event_data.vibes_device_idStringIdentifies the intended device of the triggered event message for push messages.

Note: One of the following is required:
external_person_id, mdn, person_key, person_id, or vibes_device_id		Yes*
event_idStringThe 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 in the initial call or omitted, in which case a unique ID will be generated by the Platform.

The event_id should be unique. 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_dataObjectSimilar 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

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