Tech Documentation
Knowledge BaseDeveloper HubLog In

Callbacks

Suggest Edits

Callbacks are useful for understanding the lifecycle stages of WebEngage messages. All WebEngage callbacks are called on the main thread.

New Session Started

This callback is invoked when a new session is started by our web SDK.

webengage.onSessionStarted(function(){
	//CALLBACK LOGIC GOES HERE
})

On-site Notification Callbacks

Notification Opened

This callback is invoked when the on-site notification is opened.

webengage.notification.onOpen(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"notificationId": "173049892",
	"licenseCode": "311c48b3",
	"type": "notification",
	"title": "Check out the new pricing",
	"event": "open",
	"activity": {
			"pageUrl": "http://example.com/",
			"pageTitle": "Example Title",
			"referrer": "",
			"browser": "Chrome",
			"version": 27,
			"OS": "Windows",
			"country": "United States",
			"region": "Texas",
			"city": "Dallas",
			"ip": "127.0.0.1"
		},
	"customData": {
			"userName" : [ "johndoe" ],
			"gender" : [ "male" ],
			"customerType" : [ "Gold" ],
			"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
		}
}

Notification closed

This callback is invoked when the on-site notification is closed.

webengage.notification.onClose(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"notificationId": "173049892",
	"licenseCode": "311c48b3",
	"type": "notification",
	"title": "Checkout the new pricing",
	"event": "click",
	"actionLink": "http://example.com/pricing",
	"actionText": "Check out",
	"activity": {
			"pageUrl": "http://example.com/",
			"pageTitle": "Example Title",
			"referrer": "",
			"browser": "Chrome",
			"version": 27,
			"OS": "Windows",
			"country": "United States",
			"region": "Texas",
			"city": "Dallas",
			"ip": "127.0.0.1"
		},
	"customData": {
			"userName" : [ "johndoe" ],
			"gender" : [ "male" ],
			"customerType" : [ "Gold" ],
			"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
		}
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that notification.

Notification Clicked

webengage.notification.onClick(function (data) {
    if (data.notificationId === '_NOTIFICATION_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"notificationId": "173049892",
	"licenseCode": "311c48b3",
	"type": "notification",
	"title": "Checkout the new pricing",
	"event": "click",
	"actionLink": "http://example.com/pricing",
	"actionText": "Check out",
	"activity": {
			"pageUrl": "http://example.com/",
			"pageTitle": "Example Title",
			"referrer": "",
			"browser": "Chrome",
			"version": 27,
			"OS": "Windows",
			"country": "United States",
			"region": "Texas",
			"city": "Dallas",
			"ip": "127.0.0.1"
		},
	"customData": {
			"userName" : [ "johndoe" ],
			"gender" : [ "male" ],
			"customerType" : [ "Gold" ],
			"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
		}
}

On-site Survey Callbacks

Survey Opened

This callback is invoked when the on-site survey is opened.

webengage.survey.onOpen(function (data) {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://example.com/",
		"pageTitle": "Example Title",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "United States",
		"region": "Texas",
		"city": "Dallas",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "johndoe" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	}
}

Survey Closed

This callback is invoked when the on-site survey is closed.

webengage.survey.onClose(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://example.com/",
		"pageTitle": "Example Title",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "United States",
		"region": "Texas",
		"city": "Dallas",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "johndoe" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	}
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that survey.

Survey Submit

This callback is invoked when a question is answered.

webengage.survey.onSubmit(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://example.com/",
		"pageTitle": "Example Title",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "United States",
		"region": "Texas",
		"city": "Dallas",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "johndoe" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	},
	"questionResponses": [{
		"questionId": "~1fstl7a",
		"questionText": "What is your favourite color?",
		"value": {
				"@class": "list",
				"values": ["Red"]
		}
	}]
}

Survey Complete

This callback is invoked when the on-site survey is completed.

webengage.survey.onComplete(function (data)  {
    if (data.surveyId === '_SURVEY_ID_') {
        //CALLBACK LOGIC GOES HERE
    }
});

The callback data Object in the above call looks like below.

{
	"surveyId": "~5g1c4fd",
	"licenseCode": "311c48b3",
	"activity": {
		"pageUrl": "http://example.com/",
		"pageTitle": "Example Title",
		"referrer": "",
		"browser": "Chrome",
		"version": 27,
		"OS": "Windows",
		"country": "United States",
		"region": "Texas",
		"city": "Dallas",
		"ip": "127.0.0.1"
	},
	"type": "survey",
	"title": "Survey #1",
	"totalQuestions": 6,
	"customData": {
		"userName" : [ "johndoe" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	},
	"questionResponses": [
	{
		"questionId": "~1fstl7a",
		"questionText": "Your name?",
		"value": {
			"@class": "map",
			"values": {
				"First name": "John",
				"Last name": "Doe"
			}
		}
	},
	{
		"questionId": "~1asf233",
		"questionText": "Enter your mobile number?",
		"value": {
			"@class": "text",
			"text": "+14155552671"
		}
	},
	{
		"questionId": "we2e4545",
		"questionText": "Your Bio?",
		"value": {
			"@class": "text",
			"text" : "I am an early beta user of this product."
		}
	},
	{
		"questionId": "324saf3w",
		"questionText": "What is your favourite color?",
		"value": {
			"@class": "list",
			"values": ["Red"]
		}
	},
	{
		"questionId": "~213wrw43s",
		"questionText": "Which countries you have been to?",
		"value": {
			"@class": "list",
			"values": [ "US", "Mexico" ]
		}
	},
	{
		"questionId": "~ew347fev"
		"questionText": "Rate our website",
		"value": {
			"@class" : "matrix",
			"values" : {
				"Experience" : [ "Good" ],
				"Content" : [ "Good" ],
				"Design" : [ "Poor" ]
			}
		}
	},
	{
		"questionId": "sht4k8",
		"questionText": "Upload your resume",
		"value": {
			"@class" : "file",
			"fileName" : "john_doe_resume.pdf",
			"fileSize" : 1919972,
			"fileAccessUrl" : "https://api.webengage.com/v1/download/feedback/response/ofq4jy",
			"fileType" : "pdf"
		}
	}]
}

Usage Examples

  1. Close survey after response of a particular question is submitted
webengage.init('_LICENSE_CODE_');
webengage.survey.onSubmit(function (data) {
    var surveyInstance = this;
    if(data !== undefined && data.questionResponses !== undefined && data.questionResponses.length > 0) {
        for(var i=0; i < data.questionResponses.length; i++) {
            var question = data.questionResponses[i];
            if(question["questionId"] === "324saf3w") {
                var questionResponse = question["value"];
                var values = questionResponse["values"];
                if(values !== 'undefined' &&  values.length > 0){
                    for(var k=0; k < values.length; k++) {
                        if(values[k] === 'RED') {
                            surveyInstance.close();
                            break;
                        }
                    }
                }
                break;
            }
        }
    }
});
  1. Redirect a user on survey completion
webengage.survey.onComplete(function () {
    window.location.href='/newletter/subscribe.html';
});

On-site Feedback Callbacks (Deprecated)

Feedback Opened

This callback is invoked when the on-site feedback widget is opened.

webengage.feedback.onOpen(function (data) {
       //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
		"licenseCode": "311c48b3",
		"type": "feedback",
		"activity": {
		"pageUrl": "http://example.com/page",
		"pageTitle": "Example Title",
		"ip": "127.0.0.1",
		"city": "Dallas",
		"country": "United States",
		"browser": "Firefox",
		"browserVersion": "18",
		"platform": "Linux",
		"activityOn": "2013-02-11T08:09+0000"
	},
		"customData": {
			"userName" : [ "johndoe" ],
			"gender" : [ "male" ],
			"customerType" : [ "Gold" ],
			"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
		}
}

Feedback Closed

This callback is invoked when the on-site feedback widget is closed.

webengage.feedback.onClose(function (data) {
       //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
		"licenseCode": "311c48b3",
		"type": "feedback",
		"activity": {
		"pageUrl": "http://example.com/page",
		"pageTitle": "Example Title",
		"ip": "127.0.0.1",
		"city": "Dallas",
		"country": "United States",
		"browser": "Firefox",
		"browserVersion": "18",
		"platform": "Linux",
		"activityOn": "2013-02-11T08:09+0000"
	},
		"customData": {
			"userName" : [ "johndoe" ],
			"gender" : [ "male" ],
			"customerType" : [ "Gold" ],
			"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
		}
}

🚧

The callback data for Close event will be the same as the last event (Open or Click) for that feedback.

Feedback Submitted

This callback is invoked when the on-site feedback is submitted.

webengage.feedback.onSubmit(function (data) {
        //CALLBACK LOGIC GOES HERE
});

The callback data Object in the above call looks like below.

{
	"id": "has7e2",
	"licenseCode": "311c48b3",
	"type": "feedback",
	"fields": [{
		"id": "1fcdjgf",
		"label": "Name",
		"type": "default",
		"value": {
			"@class": "name",
			"text": "John Doe"
		}
	}, {
		"id": "ah1ihjd",
		"label": "Email",
		"type": "default",
		"value": {
			"@class": "email",
			"text": "[email protected]"
		}
	}, {
		"id": "cci1868",
		"label": "Category",
		"type": "default",
		"value": {
			"@class": "category",
			"text": "Suggestion"
		}
	}, {
		"id": "~78me196",
		"label": "Message",
		"type": "default",
		"value": {
			"@class": "message",
			"text": "Thank you very much for this awesome service!"
		}
	}, {
		"id": "~5d68amb",
		"label": "Attach a screenshot of this page",
		"type": "default",
		"value": {
			"@class": "snapshot",
			"thumbnailImageUrl": ""
		}
	}, {
		"id": "n283q0",
		"label": "Enter your mobile number",
		"type": "custom",
		"value": {
			"@class": "text",
			"text": "+14155552671"
		}
	}, {
		"id": "pp3j84",
		"label": "Your Bio",
		"type": "custom",
		"value": {
			"@class": "text",
			"text": "I am an early beta user of this product."
		}
	}, {
		"id": "19jb68o",
		"label": "Which countries you have been to?",
		"type": "custom",
		"value": {
			"@class": "list",
			"values": ["US", "Mexico"]
		}
	}, {
		"id": "1cc6lks",
		"label": "Rate our website",
		"type": "custom",
		"value": {
			"@class": "matrix",
			"values": {
				"Experience": ["Good"],
				"Content": ["Good"],
				"Design": ["Poor"]
			}
		}
	}, {
		"id": "sht4k8",
		"label": "Upload your resume",
		"type": "custom",
		"value": {
			"@class": "file",
			"fileName": "john_doe_resume.pdf",
			"fileSize": 1919972,
			"fileAccessUrl": "https://api.webengage.com/v1/download/feedback/response/ofq4jy",
			"fileType": "pdf"
		}
	}, {
		"id": "16qfkqk",
		"label": "What is your favourite color?",
		"type": "custom",
		"value": {
			"@class": "list",
			"values": ["Red"]
		}
	}],
	"activity": {
		"pageUrl": "http://example.com/page",
		"pageTitle": "Example Title",
		"ip": "127.0.0.1",
		"city": "Dallas",
		"country": "United States",
		"browser": "Firefox",
		"browserVersion": "18",
		"platform": "Linux",
		"activityOn": "2013-02-11T08:09+0000"
	},
	"customData": {
		"userName" : [ "johndoe" ],
		"gender" : [ "male" ],
		"customerType" : [ "Gold" ],
		"jsessionid" : [ "CB300FEC898236FF9E5A181E468CA6BC" ]
	}
}

Usage Examples

  1. Close the feedback window 5 seconds after user submits feedback
webengage.feedback.onSubmit(function (data) {
        var feedbackInstance = this;
        setTimeout(function(){
            feedbackInstance.close();
        }, 5000);
});

Web Push Callbacks

Web Push Notification Permission Prompt Viewed

For both 1-step opt-in and 2-step opt-in, this callback is invoked when browser prompts the notification permission to the user.

webengage.options('webpush.onWindowViewed', function () {
// Callback logic goes here.
});

Web Push Notification Permission Granted

For 1-step opt-in, this callback is invoked when the user grants permission for Web Push. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user grants permission for Web Push.

webengage.options('webpush.onWindowAllowed', function () {
// Callback logic goes here.
});

Web Push Notification Permission Denied

For 1-step opt-in, this callback is invoked when the user denies permission for Web Push. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user denies permission for Web Push.

webengage.options('webpush.onWindowDenied', function () {
// Callback logic goes here.
});

Web Push Notification Permission Granted First Time

For 1-step opt-in, this callback is invoked when the user grants permission for Web Push for the first time. For 2-step opt-in, it is invoked when the custom permission prompt window closes after the user grants permission for Web Push for the first time.

webengage.options('webpush.onPushRegistered', function () {
// Callback logic goes here.
});

Web Push Notification Permission Revoked

For 1-step opt-in, this callback is invoked when the user revokes permission for Web Push after having granted it before. This callback is not available for 2-step opt-in.

webengage.options('webpush.onPushUnregistered', function () {
// Callback logic goes here.
});

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!

Updated about 2 years ago