WebEngage Notification JavaScript Callbacks - Building A Realtime Conversion Engine On Your Website

WebEngage Notification JavaScript Callbacks - Building A Realtime Conversion Engine On Your Website

Note: Breaking news first – we recently released our enhanced integration code which now supports a wide variety of JavaScript callbacks. If you are using WebEngage on your website, we recommend upgrading to the new code.

If you are new to WebEngage, take a quick live demo first – you’d love it!

Last week, we posted about our new integration code and how the callbacks can be put to some great use to build a “listening post” on your website for customers submitting feedback. Take a look at that here. This post focuses on how you can build some insanely beautiful interactions on your website using properties and callbacks in our Notification JavaScript API.

JS API awesomeness in Notification product

Our Notification product is a simple push messaging tool for your website. It allows you to display offers, run promotions and pop system alerts on your site from the comfort of WebEngage Dashboard – without changing any code on your site! Moreover, these messages can be “targeted” based on a bunch of rules. E.g. you can choose to display an offer ONLY to users “who are currently on the cart page AND haven’t checked out in 60 seconds AND have added atleast goods worth $200 or more”. Here’s more on targeting capabilities. You love us already? Wait, we haven’t even gotten started yet 🙂

Notification is an out-of-the-box product wherein all UI/targeting level customizations can be applied from the WebEngage Dashboard. That said, using our brand new JavaScript API, you can do a whole lot more – making the notification content personalized, building real-time interactions with users on a particular offer/deal etc. Take a look at the samples below.

The low hanging fruits first …
By default, a notification doesn’t get displayed to the same user once (s)he has closed the notification or clicked on any link/call-to-action in the notification. Now, by setting a property forcedRender to true, you can override this behavior. Take a look at the code sample and documentation below for other such properties. Add the corresponding properties to your integration code and see the magic unfold!

// by default, a notification doesn't get displayed to the 
// user once (s)he has closed it or clicked on any link/call-to-action 
// button in the notification. set this property to true
// if you want to override this behavior
_weq["webengage.notification.forcedRender"] = true;

// the WebEngage integration code pops a notification on 
// your website based on preset rules in the dashboard. no
// invocation is needed; however, if you'd like to manually 
// invoke a notification, you should set defaultRender to false
_weq["webengage.notification.defaultRender"] = false;

// render a particular notification by specifiying its ID
// you can get the ID of a notification from your notifications
// list page in the dashboard. Also, a notification gets
// rendered based on rules in the targeting section; if you'd
// like to skip rule execution, you'll need to additionally
// set skipRules to true 
_weq["webengage.notification.skipRules"] = true;
_weq["webengage.notification.notificationId"] = "~10cb5811a";
Creating hyper personalized messages for your users

We support tokens, which essentially is a way to display dynamic content inside notifications. Take a look at the notification below, as seen in the notification editor.

You can use any number of [[tokens]] in the editable fields – title, description, call-to-action text and URL. Through our JavaScript API, you can replace these tokens with realized values are shown underneath.

// to replace the tokens with their corresponding values, you'll need to 
// create a JSON key/value pair for all the tokens present in your 
// notification (across fields)
_weq["webengage.notification.tokens"] = { 
  userName: "John Doe"

// let's make this truly dynamic by asking you for a name which can be 
// dynamically replaced inside the notification (shown in pic above). 
// Underneath is a code. Give it a try by clicking on the "try me" 
// button below.
$("a.try", $(".notification-tokens")).click(function(){
  var name = prompt("Please enter your name", "John Doe");
  if(name != null){
    name = (name == "") ? "John Doe" : name;
    _weq["webengage.notification.tokens"] = { 
      "userName": name

    // we don't want WebEngage widget to automatically render an 
    // applicable notification as per the rules set in the dashboard
    _weq["webengage.notification.defaultRender"] = false;
    _weq["webengage.notification.skipRules"] = true;

    // we want to show the notification everytime you do a "try now" - 
    // irrespective of whether you have closed the notification once or 
    // have clicked on the call-to-action button; by default we don't 
    // show the same notification to a user once an action has been 
    // taken; this let's us override the behavior
    _weq["webengage.notification.forcedRender"] = true;

    // this is THE notification we want to render on this page
    _weq["webengage.notification.notificationId"] = "3176124c";

    // finally, render the notification!
  return false;
Implementing custom targeting rules & callback events

Custom targeting is an interesting way to display a notification (an offer / discount / recommendation etc) based on application specific criterion. E.g. Let’s say, you sell insurances online and you’d like to push a “child education plan” to customers while they are using your product online. However, you’d like to display this message ONLY to customers who have a “family group insurance”, have “atleast 1 kid” and have an “annual family income of more than $60,000”. Sounds cool? Here’s how you create such a notification and set-up its targeting criteria in your dashboard:

/* Implementing Custom Rules */

// for the custom rules, as shown above, to take effect on your website
// you'd need to pass the actual values of parameters hasGroupInsurance, 
// numberOfKids and annualFamilyIncome for logged in users.
_weq['webengage.notification.ruleData'] = {
  hasGroupInsurance: true,
  numberOfKids: 2,
  annualFamilyIncome: 75000

// with just three lines of the code above on your website, you can now
// target your notifications based any or all of the above mentioned
// customer attributes. Click the "try this example" button to see how
// this works with token data as underneath
_weq['webengage.notification.tokens'] = {
  userName: "John",
  kidsCurrentAge: 2,
  genderText: "her"

/* Implementing Callback On Click Events */

// first, you need to enable WebEngage callbacks for your widget
_weq['webengage.enableCallbacks'] = true;

/* onOpen callback */

// binding onOpen callback for your notifications
// this gets triggered anytime a notification pops-up on your website
_weq['webengage.notification.onOpen'] = function(data){

  // fetching the clickstream information for current user
  var userIP = (data.activity.ip ? data.activity.ip : "Unknown");
  var estimatedUserGeo = data.activity.city + " (" + data.activity.country + ")";
  var browser = data.activity.browser + " (" + data.activity.browserVersion + ")";
  var platform = data.activity.platform;
  var URLofThePageOnWhichFeedbackWasSubmitted = data.activity.pageUrl;
  var titleOfThePageOnWhichFeedbackWasSubmitted = data.activity.pageTitle;
  var referrer = data.activity.referrer;

  // the notification which got clicked
  var notificationId = data.notificationId;
  var notificationTitle = data.title;

  // if you are using tokens in your notification, this array
  // will contain all of them and have their corresponding values/defaults etc
  var tokens = [];
  for var(i=0; i<data.tokenData.length; i++){
    var aToken = data.tokenData[i];

    // the identifier for each token. e.g [[userName]]
    var tokenName = aToken.name;

    // you can set default value for each token in the dashboard
    var tokenDefaultValue = aToken.defaultValue;

    // the value set for each token in real-time via the JS API
    var tokenRealValue = aToken.value;


/* onClick callback */

// binding onClick callback for notifications
// if you attach this listener, every time a notification gets clicked,
// this function will be invoked
_weq['webengage.notification.onClick'] = function(data){
  // other than all the properties mentioned above, you'll
  // get these extra properties in the click event - the URL
  // and the text on the link/call-to-action button that got clicked

  var actionLink = data.actionLink;
  var actionText = data.actionText;    

/* onClose callback */

// triggers everytime a user clicks on the close button of the notification
// the data object, passed to this method, is the same as above
_weq['webengage.notification.onClose'] = function(data){
Custom data & advanced reporting
Using custom data, you can pass more information related to the customers viewing a notification or clicking on the call-to-action button. That ways, you can dice-and-slice the clickthrough information in your reporting section based on all the data you passed. Underneath is a code snippet of how to pass custom data and below that is a screenshot from the reporting section on how can clickthroughs be filtered based on these properties. Awesome. No? 😉
/* Implementing Custom Data */

// you can add a JSON key-value map to this property
// when clicks get recorded, this data gets saved along with click
// in your reporting module (screenshot below), you can filter the
// clickthrough data based on these properties

// supported data types: string, date, boolean, integer
// you can add any number of fields depending upon your plan
_weq['webengage.customData'] = {
  underTrial: false,
  domain: "userwebsite.com",
  daysInUse: 10,
  email: "admin@userwebsite.com"

That’s not all! You can do much more with other options in the API. Check out the documentation for JavaScript API (version 4.0) – docs.webengage.com along with our REST API’s and Webhooks.

Hope you liked what you saw. Do share your feedback on the API. A similar post here on how to use the JS API for our feedback product.

Stay tuned. We love you!

  • Created: 14 May 2016
  • Last Updated: 12 Jan 2022



Avlesh Singh Co-founder and CEO, WebEngage

Avlesh is the co-founder and CEO at WebEngage. He occasionally writes here and on his personal blog.

Liked our article? Give us your feedback by rating it.
Total Rating : 0 , Average Rating : 0