Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage



Using API Triggered Events

In the Vibes Mobile Engagement Platform, Events are occurrences that can be submitted into the system and linked to actions that will be executed within the system. Each event is an individual occurrence that will be checked and routed to an appropriate action for execution based on the event_type.

You can use events to trigger Platform messages. The event_data must have either a person_id, external_person_id or an MDN field to specify who will receive the message. Depending on the Event triggered messages settings in the Platform, Vibes will verify that the Person is Subscribed to your list or App before sending the message. Any other variables provided in the event_data can be used in the message template to personalize the message. 

Note

Notes:

  • An event has a maximum size of 16k. Submissions of an event that exceed that will fail with an error and will be rejected.
  • If you are using Version 2 of the APIs, then a mobile number must use the E.164 format. E.164 is the official format for all international phone numbers that includes a plus sign followed by the country code and phone number. For example:
    • U.S.: +12135551234
    • U.K.: +442135551234

Generic Event Example

The following code example shows an Event API.

Code Block
{
  "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"
  }
}


The following table shows the field name, type, description, and requirement status for the Event API.

event_data. See  APIs of   or vibes_device_id data.vibes_device_
Field NameTypeDescriptionRequired?
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

String

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 in order 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 See Person APIs APIs for the field definition.

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

Yes*
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, or person_id

is required.

Yes*
event_data.person_id

String

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

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

Yes*
event_id

String

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. Event_id is idempotent and re-using an event_id will lead to the event being ignored and no message sent.

No
debug_data

String

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

Event Triggered Message Scenario

Imagine you would like to send your customers an SMS notification on the day of a product delivery and the SMS will contain information specific to the customer's orders. You would like the message personalized to include the customer's first name, the expected delivery time, and a link to the customer's order detail.

To achieve this, you need to create an API Triggered Event in the Vibes Platform UI to be used when a delivery message needs to be sent, and the event needs to be configured to respond to the API trigger (event_type) 'day_of_delivery'.

The Message Content in the event would be defined as follows:

Hi {{ev.first_name}}! Your order will be delivered today before {{ev.delivery_time}}. For order details: {{ev.order_url}}
Reply HELP for help, Reply STOP to cancel. Msg&data rates may apply.

When the following JSON is posted to the Event API endpoint:

Code Block
{
  "event_type": "day_of_delivery",
  "event_data": {
    "first_name": "Bob",
    "mdn": "5555555555",
    "delivery_time": "5:00 PM",
    "order_url": "https://example.com/orders/12345"
  }
}


The values in the event_data object are substituted for the placeholders defined in the event Message Content and the URL is shortened, resulting in delivery of the following message to the recipient:

Hi Bob! Your order will be delivered today before 5:00 PM. For order details: http://vbs.cm/abc123
Reply HELP for help, Reply STOP to cancel. Msg&data rates may apply.

Info
Alternatively, if you know the customer has your app, you could send a push message with this information and deep link into the the order within the app.

Notes:

  • At the time of this writing, eventEvent_types (API triggers in the UI) must be created on customer request by the Vibes teamare created when configuring an API Triggered Campaign in the Vibes Platform UI.
  • Output markup for dynamic data in Message Content must be prefaced with "ev.", denoting elements of the event_data object.
    Example
    : If "first_name" is supplied in the event_data object in the API call, the Message Content markup would refer to that value as "ev.first_name".
  • Event Message Content supports Liquid Markup Language syntax.