The WebEngage Knowledge Base Developer Hub

Welcome to the WebEngage Knowledge Base developer hub. You'll find comprehensive guides and documentation to help you start working with WebEngage Knowledge Base as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started

Just like a journey, you can create a relay in WebEngage within minutes. The process of creating a relay involves the following steps:

  • Step 1: A one-off process of creating a list of business events relevant to your business in WebEngage
  • Step 2: Creating a relay
  • Step 3: Triggering the relay by triggering the business event through API, CSV uploads or manually through the dashboard

Let’s look at each of the steps above in more detail.

Step 1: Create Business Events

You have to first define a list of business events that are relevant to your business. You also have to define the attributes (and their data types) for each of these events. Please remember that this is a one-off process that you need to do for all the business events you would like to track. Therefore, we recommend that you first create this list and get the necessary approvals internally before proceeding further.

At this stage, you probably have an Excel sheet or some such document where you’ve defined a list of these business events and their attributes. For each of the business events, the list of your attributes will look something like this:

Attribute Name

Attribute Data Type

Attribute 1

String

Attribute 2

Number

Attribute 3

Date

...

...

Once you have the necessary internal approvals for the list of business events above, please visit the Data Management > Business Events section in your WebEngage dashboard, to create a list of these events in your account in WebEngage. Instead of doing this manually, you can also choose to create the list of events through REST API as covered below.

Using REST API to Create Business Events

Instead of manually creating events through the dashboard, you can also do so through our API. The following endpoint is available to create business events.

curl 'https://api.webengage.com/v2/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/business/events/definition' 
-H 'authorization: Bearer <YOUR_API_KEY>' \
-H 'Accept: application/json, text/plain, */*' 
-H 'Referer: https://dashboard.webengage.com/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/data-management/business-events/' 
-H 'Origin: https://dashboard.webengage.com' 
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36' 
-H 'Content-Type: application/json;charset=UTF-8' 
--data-binary '{
    "eventName":"<NAME_OF_BUSINESS_EVENT>",
    "attributes":
       [
        {"attributeName":"<ATTRIBUTE 1 (STRING) NAME>","dataType":"string"},
        {"attributeName":"<ATTRIBUTE 2 (NUMBER) NAME>","dataType":"number"},
        {"attributeName":"<ATTRIBUTE 3 (BOOLEAN) NAME>","dataType":"boolean"},
        {"attributeName":"<ATTRIBUTE 4 (DATE) NAME>","dataType":"date"},
        {"attributeName":"<ATTRIBUTE 5 (ARRAY) NAME>","dataType":"array"},
        {"attributeName":"<ATTRIBUTE 6 (MAP) NAME>","dataType":"map"}],
    "eventCategory":"BUSINESS"}' --compressed

After you have added all your business events in WebEngage, the Business Events section in WebEngage will look as follows.

You will now be able to trigger relays whenever any of these business events occur.

📘

Please Note: Unlike Custom Events such as Added to cart etc., you don’t have to integrate the code for triggering these events in your mobile or web SDKs.

Step 2: Create a Relay

Now that you’ve created a list of business events in WebEngage, let’s proceed to create a relay.

Click on the plus button in the Relays section on WebEngage to create a new relay.

As you can see above, the relay canvas looks quite similar to the journey canvas. However, if you notice further, you will see that the Triggers section is not available in the palette on the left in relays. Instead, you will see a trigger called When business event occurs already present on the relay canvas. Configuring this trigger will define how the relay will get triggered.

Let’s proceed and configure this trigger. Please click on the trigger block to configure it.

In the trigger configuration, you will see that you are required to specify 3 inputs:

  • Business Event: You need to select the Business Event that will trigger the relay. Each time this business event occurs, the relay will get triggered. Eg. each time a new series is added in Netflix, this relay will get triggered
  • Segment: You can choose to trigger the relay for all your users or only a segment of your users
  • Mapping of Business Event to Segment: This step contains all the magic behind relays! It helps you contextualize your relays so that a user receives only that communication that is relevant to them. Eg. If a user is interested only in Comedy, then the relay will get triggered for this user only when a Comedy series is added. Similarly, if a user is interested only in Action, then the relay will get triggered for this user only when an Action series is added.

The mapping or the contextualization happens in one of these two ways:

  • Map business event attribute to user profile attribute: In this case, you’re matching an attribute of a business event (eg. Genre attribute of business event New Series Added) to a user profile attribute (eg. User profile attribute called Interest). This will ensure that the relay gets triggered only when the value of the business event attribute is equal to (or starts with, ends with etc.) the value of the user profile attribute. Example: If a business event New Series Added occurs where the value of the Genre attribute is Comedy, then the relay will get triggered for only those users whose Interest is Comedy. Please remember that matching of these attributes requires that the data type of the business event attribute and the user profile attribute is the same. This means that you can’t compare a String data type attribute of a business event with a Number data type user profile attribute.
  • Map business event attribute to attribute of event done by user: In this case, you’re matching an attribute of a business event (eg. Genre attribute of business event New Series Added) to an attribute of an event done by user (eg. Genre Type attribute of an event done by user called Episode Watched). This will ensure that the relay gets triggered only when the value of the business event attribute is equal to (or starts with, ends with etc.) the value of the attribute of the event done by user. Example: If a business event New Series Added occurs where the value of the Genre attribute is Comedy, then the relay will get triggered for only those users who have done an event called Episode Watched where the value of the Genre Type attribute of this event is Comedy. Please remember that matching of these attributes requires that the data type of the business event attribute and the event done by the user is the same. This means that you can’t compare a String data type attribute of a business event with a Number data type attribute of an event done by user.

📘

Mapping: Please note that mapping can be done for attributes of the following data types only: Number, String, Date and Boolean. You will not be able to do mapping based on attributes of Array or Map data types.

Let’s think of a back-in-stock alert scenario for an e-commerce business. In this case, you would map the Item Code attribute of the Back in Stock business event with the Item Code attribute of an event done by the user called Product Viewed. The relay would then get triggered automatically whenever an item that the user viewed that was out of stock is added back in stock. In addition, as a result of this mapping, each user will get only those notifications that are relevant to them. Now, imagine the scale of this. Hundreds of millions of users are searching for products and viewing products multiple times a day! Relays helps you automatically contextualize your communication for each user so that they only get communication that is relevant to them.

Click the Save button to save your configuration and return to the canvas. You can now proceed to build your workflows in the exact same manner as you do in journeys. Once you’re done click the Publish Relay button to activate your relay.

Now, whenever the business event occurs, the relay will get triggered automatically!

Step 3: Trigger the Business Event

A business event can be triggered through any of the following methods:

  • Manually through the WebEngage dashboard
  • REST API
  • CSV Uploads (yet to be released)

Manually Through the WebEngage Dashboard

Visit the Business Events section under Data Management to trigger your business event manually. In this section, click on the Actions for any of the business events and then click the Trigger Event action in order to trigger the business event. Once you click the Trigger Event action, you will see a modal where you have to enter the values of the various attributes of the business event before you can trigger it. Please enter all the relevant values (you can choose to fill the values of one or more attributes and leave values as blanks for one or more attributes) and then click the Trigger Business Event button.

REST API

The following endpoint is available to trigger business events.

curl -X POST \
 'https://api.webengage.com/v2/accounts/<YOUR_WEBENGAGE_LICENSE_CODE>/business/save-event' \
 -H 'authorization: Bearer <YOUR_API_KEY>' \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/json' \
 -d '{
 "eventName":"<NAME_OF_BUSINESS_EVENT>",
 "eventTime":"2019-01-05T13:06:56+0530",
 "eventData":{
   "<ATTRIBUTE 1 (STRING) NAME>":"Abc Xyz",
   "<ATTRIBUTE 2 (NUMBER) NAME>":1,
   "<ATTRIBUTE 3 (BOOLEAN) NAME>":True
   "<ATTRIBUTE 4 (DATE) NAME>":2019-02-07T12:07:50+0530
   "<ATTRIBUTE 5 (ARRAY) NAME>":[1,2,3...]
   "<ATTRIBUTE 6 (MAP) NAME>": <Map>
 }
}'

📘

Please Note: The eventTime field above is optional and you can choose to not include it in your API call.

CSV Uploads

You will also be able to trigger business events by uploading CSV files. This functionality is not currently available and will be made available soon.

Updated about a year ago

Getting Started


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.