Skip to end of metadata
Go to start of metadata

Last Updated: Wednesday, January 29, 2020



Using API Triggered Events

The Vibes Mobile Engagement Platform can be configured to respond to events that are submitted to it from other external applications. Incoming events will be handled and routed based upon the event_type value in the event object. Several actions can be taken as a result of these events, including sending sms messages through the Platform.

The Platform can also accept event_data that can be used to personalize these event-triggered messages. Certain event_data is required (such as a person_id, external_person_id or MDN to ensure a subscriber is valid and to properly route the message). However, this data can also include a wide variety of data to include in messages such as customer names, order numbers, and even URLs.

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

API Triggered Event Entity

The following describes an API Triggered Event entity in the Vibes Platform. Field definitions follow.

{
  "event_id": "2d4a2",
  "event_type": "day_of_delivery",
  "event_data": {
    "first_name": "Bob",
    "external_person_id": "abcd12345",
    "order_description": "2 large packages",
    "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.

*Note: One of the following fields (external_person_id, mdn, person_idor vibes_device_id) must be included in the event_data.

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, person_idor 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, person_idor vibes_device_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, person_idor vibes_device_id is required.

Yes*
vibes_device_idString

Identifies the intended device of the triggered event message (push messages only).

*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 of {{ev.order_description}} will be delivered today. For order details: {{ev.order_url}}
Reply HELP for help, Reply STOP to cancel. Msg&data rates may apply.

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

{
  "event_type": "day_of_delivery",
  "event_data": {
    "first_name": "Bob",
    "mdn": "5555555555",
    "order_description": "2 large packages",
    "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 of 2 large packages will be delivered today. 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 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.
  • Events will immediately trigger messages and can't be scheduled in advance.
  • No labels