Skip to main content

Events

Events are occurences that happen in a platform or system.

For example, let's consider a customer support chatbot for an e-commerce platform. When a user initiates a conversation, a welcome event is triggered, presenting a greeting message along with options for the user to select from.

You can use these events to trigger specific bot flows, run campaigns, or perform any other actions based on your requirements.

Types of events in yellow.ai

The following are the different types of events available for different modules.

The following are the events available for our chat widget.

EventDescription
bot-openedFor websites: When a user clicks on the chat bubble to open the bot.
For PWA: When the bot loads.
bot-closedWhen the user closes the bot.
bot-loaded-on-page-reloadWhen the user reloads the current bot page or the page gets reloaded automatically.
ym_homeWhen the user clicks the home button.
ym_closed_promotionWhen the user closes the promotion in the bot.
page-url-based-triggerTriggers based on a specific URL or webpage.

Refer to this doc for inbox events.

The following are the events available for Engage.

This event occurs when a user clicks on Quick reply option in whatsapp.

Event schema

{
"event": {
"code": "quick_reply_event",
"data": "Haan, vapas aana hai",
"templateName": "Template name",
"userId": "919533211xxx",
"campaignId": "apiNotifications",
"extraParams": {
"campaignId": "apiNotifications",
"templateId": "element name:”Template name",
"workflowId": "null"
}
}
}

Facebook Click-to-WhatsApp Campaign Event

This event is triggered by Facebook campaigns that utilize the Click-to-WhatsApp feature, which allows users to navigate directly to WhatsApp from the ad.

When a user interacts with a Facebook ad, a referral event is received by the bot, containing information about the user and the campaign.

Prerequisites
  1. The Facebook page where the campaigns are run should be linked with a WhatsApp Business Account number which is integrated with the bot. See how to do it.
  2. The following events need to have enabled from the event hub for that particular bot.
  • whatsapp-referral
  • fb-ad-referral

The referral event follows the following process:

  1. The user clicks on an ad that has the Click-to-WhatsApp call-to-action (CTA) configured.
  2. The user is redirected to WhatsApp with a pre-configured message related to the ad.
  3. To trigger the referral event in the bot, the user needs to send the pre-configured message without making any edits.
  4. The advertising business receives an inbound message notification that includes the referral property. This referral property provides additional context about the ad that triggered the message.
  5. The business can utilize the information received from the event to appropriately respond and engage with the user.
note

If the user modifies the pre-configured message, the referral event will not be triggered.

By leveraging the referral event and the associated information, businesses can effectively track the success of their Facebook Click-to-WhatsApp campaigns and tailor their responses accordingly.

You can get the following fields in your referral event object:

FieldDatatypeDescription
headlineStringRepresents the text used in the ad that generated the message.
bodyStringRepresents the source type of the ad. Supported values are "ad" and "post".
source_idStringRepresents the Facebook ID for an ad or a post.
source_urlStringRepresents the URL that leads to the ad or post. Opening this URL takes you to the ad viewed by the user. A referral object may contain only the source_url field in some cases. This can happen if:
  • A user sends the message before the context for the ad or post has been rendered on the user’s app.
  • An error or mismatch occurs when the user's client tries to look for the ad or post’s context.
image and videoMedia objectRepresents the image or video that the user saw and clicked. This object will not appear if the skip_referral_media_download application setting is set to true. See application settings for more details.

drawingdrawing

Sample event data that will be captured in bot logs

"event":
{
“code”:“whatsapp-referral”,
"data": {
"body":"Find the quickest answers to the hardest questions with EMBIBE’s Doubt Resolution",
"headline":"Chat with us",
“source_id":“23849768127610425",“source_type":"ad",
“source_url":"https://fb.me/1h8GtCKq7",
“video":{

"id":"42ac72f-204d-4f5b-81f4-f09bf1952253"
},
“message":“How can I use the Doubt Resolution feature?"
}
}


The integration related events depend completely on the events the respective third-party app supports. Hence, the list of supported events might vary for each integration.

EventDescription
shopifyCustomerUpdateWhen there's an update to a customer's information in a Shopify store.
shopifyNewOrderThis event occurs when a new order is created in a Shopify store, indicating a customer's purchase.
shopifyNewProductWhen a new product is added to the Shopify store's inventory.
shopifyOrderCancelledThis event happens when an order in the Shopify store is canceled.
shopifyOrderFulfilledWhen an order is marked as fulfilled, indicating that it has been shipped or completed.
shopifyOrderPaidWhen an order in the Shopify store is marked as paid.
shopifyRefundCreatedWhen a refund is created for an order in the Shopify store.
shopifyNewCustomeWhen a new customer is added to the Shopify store.
shopifyCheckoutCreatedWhen a customer initiates the checkout process in the Shopify store.
shopifyCheckoutUpdateWhen there's an update to a checkout in progress.
shopifyOrdersUpdatedWhen there are updates or modifications to existing orders in a Shopify store.
shopifyCartCreateWhen a customer creates a shopping cart in the Shopify store, indicating their intent to make a purchase.
shopifyCartEmptyWhen a customer empties their shopping cart, indicating the removal of items they previously intended to purchase.
shopifyUserSessionCreateWhen a user initiates a session in the Shopify store, typically by logging in or visiting the site.
shopifyUserSessionUpdateWhen there's an update or change in the user's session within the Shopify store.

User inactivity events

User inactivity event refers to a specific event that is triggered when a user remains inactive or doesn't respond to the bot's prompts for a certain period of time.

For example, if we ask for an email and get no response, we may check if they are still available or repeat the request. Options include sending a message, repeating the prompt, or starting a new flow to handle inactivity.

For a detailed use case guide on this event, click here.

To create user inactive events:

  1. Go to Studio > Event > User inactivity events > + Add event.

  2. In Event name, provide a name to that event.

    drawing
  3. In Event description, describe that event.

  4. In Event delay, type the inactive time in minutes/seconds.

  5. Activate Activate for specific steps to activate this event for a certain step in a flow.

  6. Activate Handle event with message to display a message when a user has been inactive.

  7. Enable Show previous prompt to nudge the user to provide answer to the question.

  8. Click Create event.

Schedule events

Schedule events are used to define the exact timing at which a workflow of your choice need to be triggered. Schedule events work only for flows that have been created as a workflow. To know about workflows in detail, click here.

By setting up Schedule events, you can determine when certain actions or processes within your system should be executed, providing better control and automation over your workflows.

To schedule an event:

  1. Go to Schedule events > +Add Event

  2. In Event name, enter the name of the event.

drawing
  1. In Event description, describe that event.
  2. Choose any option under Execute event.
FieldsDescriptions
OnceExecute the event once on a specific date and time.
RecurringSet regular event occurrences with options like Hourly, Daily, Weekly, or Monthly intervals. Customize timing based on Minutes, Time, Date, or Day. Choose Timezone and End date for concluding recurring events.
AdvancedUse cron expressions for flexible scheduling of complex scenarios. Cron expressions consist of six or seven subexpressions (fields) defining various schedule aspects. This option offers greater control over event timing and execution.
note

It is advisable to use the Advanced option solely for intricate use cases that cannot be accommodated through Once or Recurring. Familiarity with Cron expressions is essential when utilizing this feature.

  1. In Date and Timezone, choose the date and timezone in which the event should be carried out.
  2. Click Create event.
note

By default, a scheduled event is in activate state. You can deactivate, edit, or delete the event by using the more options icon.

User 360 events (System events)

These are sytem events that helps in triggering flows or perform actions on user profile related activities - when a user is created, user details are updated, and user profile is deleted.

The following are some real-time use cases that you can solve with these events:

  • Send onboarding campaigns when a new user is created
  • Send message when a user information is updated or deleted.
  • Sync data to an external CRM through APIs when a user is added/upated/deleted.
  • Sync data from an external database through APIs when these events occur.
EventDescriptionSample payload
USER_CREATEWhen a user record is created in (CDP) DB through any of the following operations:
- Single User Creation in UI
- User Creation through Builder
- User Creation through API
- User Creation through CSV Import
{
"id": "IN5TK-OyZekJUT2xldP1J",
"botId": "x1659503658437",
"userId": "[email protected]",
"event": "USER_CREATE",
"source": "SYSTEM",
"payload”: {
"timestamp": 1666340842464,
"user": {
"firstName”: "Jolly",
"gender": "FEMALE",
"profileComplete": "17.65",
"userId": "[email protected]"
},
"userId": "[email protected]"
},
"createdAt": "2022-10-21T08:27:23.000Z"
,
"updatedAt": "2022-10-21T08:27:23.000Z"
,
"deletedAt": null
}
USER_UPDATEWhen a user record is updated in (CDP) DB through the following operations:
- Single User Updation in UI
- User Updation through Builder
- User Updation through API
- User Updation through CSV Import
Setting an unset field:
{
"id": "5IjS7mCLBEWehufVSa3Jj",
"botId": "x1659503658437",
"userId": "[email protected]",
"event": "USER_UPDATE",
"source": "SYSTEM",
"payload": {
"newPayload": {
"city": "Bengaluru",
"country": "IN",
"lastName": "Harsha",
"profileComplete": "35.29"
},
"oldPayload": {
"city": null,
"country": null,
"lastName": null,
"profileComplete": "17.65"
},
"timestamp": 1666352773812,
"userId": "[email protected]"
},
"createdAt": "2022-10-21T11:46:15.000Z",
"updatedAt": "2022-10-21T11:46:15.000Z",
"deletedAt": null
}
Updating an already set field:
{
"id": "O0-AanNYjvHzWB-l62tKM",{
"botId": "x1659503658437",{
"userId": "[email protected]",{
"event": "USER_UPDATE",{
"source": "SYSTEM",{
"payload": {{
"newPayload": {{
"city": "Mysore"{
},{
"oldPayload": {{
"city": "Bengaluru"{
},{
"timestamp": 1666353518569,{
"userId": "[email protected]"{
},{
"createdAt": "2022-10-21T11:58:40.000Z",{
"updatedAt": "2022-10-21T11:58:40.000Z",{
"deletedAt": null{
}
USER_DELETEWhen a user record is updated in (CDP) DB through any of the following operations:
- Single User Updation in UI
- Bulk User Deletion from UI
- User Deletion during MERGE
- User Deletion through API
{
"user": {
"firstName": "kumar",
"userName": "sasi",
"userId": "10"
},
"userId": "10",
"timestamp": 1657713515000
}

Custom events

In addition to the standard events available, you have the flexibility to create custom events that allow you to perform various actions and activities not listed on th events page.

To create a custom event, follow these steps:

  1. Go to Studio > Event Custom events > +Add Event.

  2. Add Event name and Event description.

  3. Then, push the event data using the Push user event POST /v1/internal/event/ API.

note
  1. The above-mentioned API doesn't allow genric payloads and cannot be used as a general webhook.
  2. Once a custom event is created, you can activate, deactivate, edit or delete a custom event.

Whatsapp events

Whatsapp events refer to the events related to Whatsapp.

EventDescription
whatsapp-product-queryWhen a user enquires about a product on whatsapp
whatsapp-cartWhen a user adds a product to the cart on Whatsapp

Activate events

For the bot to perform certain actions when an event occurs, the event needs to be activated. To activate an event and use it in your flow,

  1. Go to Event and click any module (except Schedule, User 360, Custom and User events, refer the docs above to create those events)

  2. Click more and click Activate on the respective event.

  3. Go to a flow and include that event in the Start node and build the flow to carry out the action when that event occurs.

Deactivate/Delete events

Deactivate will deactivate an event and delete will remove that event from the platform.

info

You cannot delete standard events, only custom events can be deleted

To deactivate/delete an event,

  1. Go to Event > click any module.

  2. Click more and click Deactivate or Delete on the respective event.