Skip to end of metadata
Go to start of metadata

Last Updated: Wednesday, June 10, 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

Details on the API Triggered Event entity and endpoint are available here.


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'.

In platform, you would create this event_type by entering its name in the section that asks for an API trigger (see photo below). 



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