An event-triggered campaign entity is a message template that is triggered to be sent after the Vibes system receives an event. You can configure and request information about event-triggered campaigns using public API calls.

You can create these campaigns either in the platform or via an API call. To learn how to do it in the platform, please see this guide.

It’s important to note that creating this template won’t automatically send a text message or push notification. Once the template is set up, the message will only be sent if an event of the specified event_type is sent to the Vibes system.

To learn how to define an event, see our Event API.

Available API Methods

Available Callbacks

Event-triggered callbacks

Elements & Attributes

Element	Type	Description	Required?
`event_triggered_message_id`	Integer	Unique identifier for each event-triggered message campaign.	no (system generated)
`status`	String	The status of the event-triggered campaign. Possible values include (always lowercase): - `scheduled`: the campaign will become active on the `start_date` - `in_progress`: the campaign is active - `ended`: the campaign is no longer active because the `end_date` has passed - `canceled`: The campaign has been canceled	no (system generated)
`name`	String	The descriptive name of the event-triggered campaign. Example: "Order update SMS message".	yes
`event_type`	String	Events that are POST-ed with the same event_type value will invoke this message template. Valid characters are alphanumeric, dash and underscore. Note: `event_type` values are NOT case sensitive.	yes
`start_date`	Timestamp	ISO-8601 format: yyyy-mm-dd Date string indicating when the status should become in_progress. This field is required on-create (`POST`) but may be left blank on update (`PUT`). Once the `start_date` has passed and the status becomes `in_progress`, this value may not be changed (must exactly match current value if included). For new or scheduled messages, this value may be set in the past, causing the status to immediately become `in_progress`.	yes (on-create)
`end_date`	Timestamp	ISO-8601 format: yyyy-mm-dd Date string indicating when the campaign status should become `ended`. Leaving this value blank (null) results in an open-ended campaign. Must be later than the `start_date`. May not be changed once the `end_date` (if set) has passed and the status is `ended`.	no
`targeting`	Object	The targeting information for the event-triggered campaign, including message content, filter criteria, and channel-specific attributes.	yes
`targeting.message_template`	String	Templated message content that will be rendered for a given recipient. May include valid Liquid personalization tags, including: - Attributes from the Event API call – e.g., `{{ ev.order_id }}` - Mobile database custom fields – e.g., `{{ first_name }}` - other custom mobile database tags e.g. `{{ cm.wallet \| token: “xyz123” }}` or `{{ incentive_code \| pool_id: 1 }}`	For SMS & push: yes For MMS: no
`targeting.short_url_base`	String	A valid HTTP URL that has been registered for use with Vibes URL shortener. Defaults to NULL if not provided. When NULL, will use the Vibes system default URL for the environment and region (e.g., US Production is "http://vbs.cm").	no
`targeting.shorten_urls`	Boolean	If set to true, any URLs found in the message content will be converted to a unique short URL for each recipient. URL shortening is the final rendering step, enabling dynamic short URLs to be generated per-recipient by using Liquid tags in the URL.	yes (on-update
`targeting.channel`	String	The delivery channel associated with this message. Current valid options are: SMS or PUSH. May not be changed on-update. An additional SMS or PUSH attribute should be included, matching the specified channel (see below).	yes
`targeting.message_format`	String	A read-only field that defines the message format. If the targeting channel is sms, the value will be `sms` or `mms`. If the targeting channel is push, the value will `push`.	no
`targeting.sms`	Object	Channel-specific attributes for SMS messages.	yes, for SMS sends
`targeting.sms.sourcecode`	String	The short, long or alphanumeric code value.	yes, for SMS sends
`targeting.sms.country_code`	String	The E.164 Country Calling Code for the country where the code is provisioned.	yes, for SMS sends
`targeting.sms.sourcecode_type`	String	"SC" for short or long numeric codes; "ANC" for alphanumeric codes.	yes, for SMS sends
`targeting.mms`	Object	Channel-specific attributes for MMS messages. Note: MMS is supported in the US only.	yes, for MMS sends
`targeting.mms.sourcecode`	String	The short, long or alphanumeric code value.	yes, for MMS sends
`targeting.mms.country_code`	String	The E.164 Country Calling Code for the country where the code is provisioned.	yes, for MMS sends
`targeting.mms.sourcecode_type`	String	"SC" for short or long numeric codes; "ANC" for alphanumeric codes.	yes, for MMS sends
`targeting.mms.subject`	String	The subject line that will appear in your mms send. Limit 50 characters.	no
`targeting.mms.content [ ]`	List of objects	An object containing a list of objects for your MMS. Your MMS may contain either an uploaded asset or a media URL, which represent the media part of your send. Sends with an uploaded asset or media URL may also contain text in a `body` object after the media object. You can also have a text-only send, in which case `body` will be the only object.	yes, for MMS sends
UPLOADED ASSET ELEMENT `targeting.mms.content[].asset_id`	String	A read-only string identifying the asset. Note: MMS sends using uploaded assets must be created in the Vibes UI Platform. After the asset is uploaded, an `asset_id` will be generated, but can only be accessed via API calls.	no
UPLOADED ASSET ELEMENT `targeting.mms.content[].mime_type`	String	A read-only string identifying the MIME type of the uploaded asset. For example: `image/jpeg`	no
MEDIA URL ELEMENT `targeting.mms.content[].media_url`	String	A URL link to the media to be included in the MMS OR If you are personalizing the media element, you can add a liquid template variable . The `media_url` should then be present in the event payload. Notes for using an URL: - Include the HTTP or HTTPS portion of the URL. - The URL must be publicly available. - The URL will be fetched when the MMS is triggered to be sent. - The response must be under 500KB. - Available MIME types are: image/jpeg, image/png, or image/gif. - If the URL is unavailable at send time or the response is too large, the message will fail to send.	yes, if including a media url element
MEDIA URL ELEMENT `targeting.mms.content[].description`	String	An optional description of the media.	no
TEXT ELEMENT `targeting.mms.content[].body`	String	The body text included in the MMS send.	yes, if including text
TEXT ELEMENT `targeting.mms.content[].mime_type`	String	A string identifying the MIME type of the element. Must be text/plain for the `body` object.	yes, if including text
`targeting.push`	Object	Channel-specific attributes for Push messages.	yes (if channel="push”)
`targeting.push.mdn_territory`	String	ISO 2-character country code (such as "US" or "GB") that represents the territory non-E.164 MDNs are expected to be in (when submitted through the Event API). The MDNs will be parsed and validated against number patterns for that territory. If not supplied, `mdn_territory` will default to an appropriate value based on the `country_code`.	no
`targeting.push.app_id`	String	Vibes-specific UUID for the specific app.	Yes (both iOS and Android)
`targeting.push.silent_push`	Boolean	A silent—or “background”—push will send information to the app without sending a visible message to the customer. Typically used in combination with custom properties, this function will wake up the app for a specific prebuilt function.	no (both iOS and Android)
`targeting.push.subject`	String	Subject line displayed in a push message. Supports personalization using Liquid tags.	no (both iOS and Android)
`targeting.push.media_url`	String	Rich Media adds an image, video, or audio file for iOS or an image to a notification. Requires Rich Media support in the operating system and device hardware. Supports personalization using Liquid tags.	no (both iOS and Android)
`targeting.push.sound`	String	App notification sound may be customized to a brand specific sound or set to the user's device default. The notification sound defaults to silent. Custom sounds must be built into the app.	no (both iOS and Android)
`targeting.push.badge`	String	Badge count will reset the total badge value on the app icon.	no (iOS only)
`targeting.push.metadata`	String	Arbitrary metadata sent to the app when the mobile consumer taps on the push notification. It is not seen by the user and can be used for deep-linking or customization purposes.	no (both iOS and Android)
`targeting.push.client_custom_data`	Object	Custom Properties are used to send information to the app when the mobile consumer taps on the push notification. It is not seen by the user and can be used for deep linking or customization purposes. 10 rows maximum. Supports personalization using Liquid tags.	no (both iOS and Android)
`targeting.push.collapse_id`	String	Identical `collapse_id` values on two notifications will allow a previous notification to be replaced with an incoming notification. If not populated, this value will be set to a unique default value, so it will always be possible to replace a notification. Supports personalization using Liquid tags.	no (both iOS and Android)
`targeting.push.category`	String	A category can be used to trigger predefined actions that have been built into your app. iOS only.	no (iOS only)
`targeting.push.notification_channel`	String	Notification channel, aka category, is used to group certain types of notifications together so apps can configure specific actions and users can manage their opt-in status per channel.	no (Android 8+ only)
`targeting.push.expiration_offset`	Integer	OS Expiration is how long Apple or Google will attempt to send the message if the device is offline, up to 28 days. If 0, the message will attempt to send just once. Value is in milliseconds.	no (both iOS and Android)
`targeting.filters`	Array	An array of filter objects that can be used to restrict the target recipients for this message. If not included, this is equivalent to setting it to an empty array.	no (defaults to empty set)
`targeting.filters.name`	String	Name of the filter that is being used.	yes
`targeting.filters.transform`	String	Optional transform (depends on type of filter being used)	no
`targeting.filters.selector`	String	Method of selection. Options include: any, all, and various others depending on the type of filter being used.	yes* if `targeting.filters` array is used.
`targeting.filters.value`	Array	An array of values to filter on. The type and valid options depend on the filter being used.	yes
`url`	String	Unique resource URL for the event-triggered campaign.	no (system generated)
`created_by`	String	The email address or user ID of the person who created the event-triggered campaign.	no (system generated)
`created_by_application`	String	The application used to create the event-triggered campaign.	no (system generated)
`created_at`	Timestamp	ISO-8601 Date string indicating the date and time at which this event-triggered campaign was created.	no (system generated)
`updated_at`	Timestamp	ISO-8601 Date string indicating the date and time at which this event-triggered campaign was last updated.	no (system generated)

Entity Examples

The following is the JSON representation of an Event-Triggered SMS Campaign entity within the APIs.

{
  "event_triggered_message_id": 1,
  "status": "scheduled",
  "name": "Order Delivered SMS Message",
  "event_type": "order_delivered",
  "start_date": "2020-12-01T23:00:00Z",
  "end_date": null,
  "created_by": "123",
  "created_by_application": "API",
  "targeting": {
    "message_template": "Your order #{{ ev.order_id }} has been successfully delivered!",
    "short_url_base": "http://vbs.cm",
    "shorten_urls": true,
    "channel": "sms",
    "sms": {
      "sourcecode": "12345",
      "country_code": "1",
      "sourcecode_type": "SC",
      "mdn_territory": "US"
    },
    "filters": []
  },
  "url": "/companies/xyz123/mobiledb/event_triggered_messages/1",
  "created_at": "2020-12-01T22:24:46Z",
  "updated_at": "2020-12-01T22:24:46Z"
}

The following is the JSON representation of an Event-Triggered MMS Campaign entity with only a subject and text element.

{
  "event_triggered_message_id": 2,
  "status": "scheduled",
  "name": "Order Delivered SMS Message",
  "event_type": "order_delivered",
  "start_date": "2020-12-01T23:00:00Z",
  "end_date": null,
  "created_by": "123",
  "created_by_application": "API",
  "targeting": {
    "message_template": null,
    "short_url_base": "http://vbs.cm",
    "shorten_urls": true,
    "channel": "sms",
    "message_format": "mms",
    "mms": {
      "sourcecode": "12345",
      "country_code": "1",
      "sourcecode_type": "SC",
      "mdn_territory": "US",
      "subject": "Order #{{ ev.order_id }} update",
      "content": [
        {
          "body": "Your order #{{ ev.order_id }} has been successfully delivered!",
          "mime_type": "text/plain"
        }
      ]
    },
    "filters": []
  },
  "url": "/companies/wZVasTXH/mobiledb/event_triggered_messages/1",
  "created_at": "2020-12-01T22:24:46Z",
  "updated_at": "2020-12-01T22:24:46Z"
}

The following is the JSON representation of an Event-Triggered MMS Campaign entity that includes a subject, text, and an asset uploaded into the Vibes UI.

{
  "event_triggered_message_id": 2,
  "status": "scheduled",
  "name": "Order Delivered SMS Message",
  "event_type": "order_delivered",
  "start_date": "2020-12-01T23:00:00Z",
  "end_date": null,
  "created_by": "123",
  "created_by_application": "API",
  "targeting": {
    "message_template": null,
    "short_url_base": "http://vbs.cm",
    "shorten_urls": true,
    "channel": "sms",
    "message_format": "mms",
    "mms": {
      "sourcecode": "12345",
      "country_code": "1",
      "sourcecode_type": "SC",
      "mdn_territory": "US",
      "subject": "Order #{{ ev.order_id }} update",
      "content": [
        {
          "asset_id": "86f03b74-63da-4295-82ac-83a4b1ac8219",
          "mime_type": "image/jpeg"
        },
        {
          "body": "Your order #{{ ev.order_id }} has been successfully delivered!",
          "mime_type": "text/plain"
        }
      ]
    },
    "filters": []
  },
  "url": "/companies/wZVasTXH/mobiledb/event_triggered_messages/1",
  "created_at": "2020-12-01T22:24:46Z",
  "updated_at": "2020-12-01T22:24:46Z"
}

The following is the JSON representation of an Event-Triggered MMS Campaign entity that includes a subject, text, and a URL link to the media to include in your message. Note that you can also replace the URL with a liquid template variable.

{
  "event_triggered_message_id": 2,
  "status": "scheduled",
  "name": "Order Delivered SMS Message",
  "event_type": "order_delivered",
  "start_date": "2020-12-01T23:00:00Z",
  "end_date": null,
  "created_by": "123",
  "created_by_application": "API",
  "targeting": {
    "message_template": null,
    "short_url_base": "http://vbs.cm",
    "shorten_urls": true,
    "channel": "sms",
    "message_format": "mms",
    "mms": {
      "sourcecode": "12345",
      "country_code": "1",
      "sourcecode_type": "SC",
      "mdn_territory": "US",
      "subject": "Order #{{ ev.order_id }} update",
      "content": [
        {
          "media_url": "https://example.com/delivered.jpeg",
          "description": "Delivery image"
        },
        {
          "body": "Your order #{{ ev.order_id }} has been successfully delivered!",
          "mime_type": "text/plain"
        }
      ]
    },
    "filters": []
  },
  "url": "/companies/wZVasTXH/mobiledb/event_triggered_messages/1",
  "created_at": "2020-12-01T22:24:46Z",
  "updated_at": "2020-12-01T22:24:46Z"
}

The following is the JSON representation of an Event-Triggered Push Campaign entity within the APIs.

{
  "event_triggered_message_id": 2,
  "status": "in_progress",
  "name": "Order Delivered Push Message",
  "event_type": "order_delivered",
  "start_date": "2020-12-01T23:00:00Z",
  "end_date": null,
  "created_by": "123",
  "created_by_application": "API",
  "targeting": {
    "message_template": "Your order #{{ ev.order_id }} has been successfully delivered!",
    "short_url_base": null,
    "shorten_urls": false,
    "channel": "push",
    "push": {
      "app_id": "6e4f85c9-5cc9-4925-8ea7-398630ef7e3f"
    },
    "filters": []
  },
  "url": "/companies/xyz123/mobiledb/event_triggered_messages/2",
  "created_at": "2020-12-01T22:55:44Z",
  "updated_at": "2020-12-01T23:16:26Z"
}