Skip to end of metadata
Go to start of metadata

Last Updated: Wednesday, August 21, 2019



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. 

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.

{
  "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.

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

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, or person_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*
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, or person_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:

{
  "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.

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:

  • Event_types (API triggers in the UI) are 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.
  • No labels