Last Updated:



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.

Considerations:

  • Use meaningful Event Types that describe the event in some way. The same concept applies to tokens in the message template.
  • Rather than constructing the entire message and passing it to the Event, try creating a template and only providing in the Event payload the dynamic data to populate the template.
    • This is especially true if you are sending smart links in events. Put the smart link in the template and only pass in data that is unique to the pass being delivered.
  • The Event API will accept 300 requests/second. If you anticipate greater volume, consider using a message queue to send the requests so retries and throttling can be applied if necessary.

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 Template Language syntax.
  • Events will immediately trigger messages and can't be scheduled in advance.