JavaScript API - Listeners/Events

These event will triggers only when Pingstreams Widget fired some event in a specific situation. Once it’s up, you’ll be able to do something you need in the function handler.

window.Pingstreams(event_name, handler)

Register an event handler to an event type.

Available events:

Event	Description
onLoadParams	Fired when the parameters are loaded*
onInit	Fired when the widget is initialized
onAuthStateChanged	The event is generated when the user logs in or logs out
onOpen	Fired when the widget is open
onClose	Fired when the widget is closed
onBeforeMessageSend	Fired before the message sending
onAfterMessageSend	This event is generated after the message has been sent
onOpenEyeCatcher	Fired when the callout box is open
onClosedEyeCatcher	Fired when the callout box is closed
onCloseMessagePreview	Fired when the user click on close button in message preview while new message is received and widget is closed
onNewConversationComponentInit	Fired just after a new conversation is initialized
onBeforeDepartmentsFormRender	Fired just before rendering Departments in the Departments view
onMessageCreated	Fired when the widget receive a message
onNewConversation	Fired when the widget start a new conversation
onConversationUpdated	Fired when the widget receive a conversation update

*This event will be fired before the pingstreams parameters is loaded. Use this event to change at runtime your Pingstreams settings.

Initial events lifecycle:

onLoadParams → onInit → onAuthStateChanged

The handler will have the signature function(event_data).

event_data is a Javascript CustomEvent. More info about CustomEvent here

Arguments:

Parameter	Type	Required	Description
event_name	String	YES	Event name to bind to
handler	Function	YES	Function with the signature function(event_data)

Important payload of event_data:

Property	Type	Description
detail.default_settings	Object	the constructor default settings

Example: Logging of widget events

<script type="application/javascript">
window.Pingstreams('onBeforeMessageSend', function(event_data) {
var message = event_data.detail.message;
console.log("onBeforeMessageSend called ", message);
});

window.Pingstreams('onAfterMessageSend', function(event_data) {
var message = event_data.detail.message;
console.log("onAfterMessageSend called ", message);
});
</script>

Example: Widget with visitor fullname and email from localStorage

<script type="application/javascript">
//set fullname to localstorage
localStorage.setItem("user_fullname", "Andrea from localStorage");
localStorage.setItem("user_email", "andrea@example.com");

window.Pingstreams('onLoadParams', function(event_data) {
window.pingstreamsSettings.userFullname = localStorage.getItem("user_fullname");
window.pingstreamsSettings.userEmail = localStorage.getItem("user_email");
});
</script>

Example: Widget with welcome message with current date

<script type="application/javascript">
window.Pingstreams('onLoadParams', function(event_data) {
window.pingstreamsSettings.welcomeMsg = " Hello at: " + new Date().toLocaleString();
});
</script>

onBeforeMessageSend

This event will be fired before the message sending. Use this event to add user information or custom attributes to your chat message.

Important payload of event_data:

Property	Type	Description
detail.message	Object	the message that is being sent

Example: Programmatic setting custom user metadata

<script type="application/javascript">
window.Pingstreams('onBeforeMessageSend', function(event_data) {
var message = event_data.detail.message;
message.attributes.userCompany = "Frontiere21";
});
</script>

Example: Add a custom attribute (page title) to the message

<script type="application/javascript">
window.Pingstreams('onBeforeMessageSend', function(event_data) {
var message = event_data.detail.message;
message.attributes.pagetitle = document.title;
});
</script>

onAfterMessageSend

This event is generated after the message has been sent.

Important payload of event_data:

Property	Type	Description
detail.message	Object	the message that was sent

Example:

<script type="application/javascript">
window.Pingstreams('onAfterMessageSend', function(event_data) {
var message = event_data.detail.message;
console.log("onAfterMessageSend called ", message);
});
</script>

onAuthStateChanged

This event is generated when the authentication state changed (Ex: user sign-in, user logout, etc.)

Important payload of event_data:

Property	Type	Description
detail	Object	the auth event

Auth Event description:

Property	Type	Description
event	string	Possible values: ‘online’ when user is logged in, ‘offline’ when user is logged out
isLogged	boolean	Possible values: true if the user is logged, false if not logged
user_id	string	The current user identifier
global	object	An object with all the widget global parameters
default_settings	object	The initial widget config parameters (window.pingstreamsSettings)
appConfigs	object	The remote widget config parameters obtained from the remote Pingstreams server

Example:

<script type="application/javascript">
window.Pingstreams('onAuthStateChanged', function (event_data) {
console.log("onAuthStateChanged ----> ", event_data.detail.event);
if (!event_data.detail.isLogged) {
console.log("NOT logged");
window.pingstreams.signInWithCustomToken("JWT CHANGE IT");
} else {
console.log("logged in");
}
});
</script>

onBeforeDepartmentsFormRender

This event is generated before rendering the Departments selection View. Use this event if you want to filter the default Departments list based on some conditions.

Important payload of event_data:

Property	Type	Description
detail.departments	Object	the array of the default Departments

Example:

In the following example Departments are filtered based on the current widget language. Actually a Department doesn’t provide a specific “language” field. In this example Department language is put in the Department description field. Attention you can modify the departments array only by reference.

<script type="application/javascript">
window.Pingstreams('onBeforeDepartmentsFormRender', function(event_data) {
var departments = event_data.detail.departments;
var lang = window.pingstreams.angularcomponent.component.g.lang;
if (lang && lang === 'en') {
var new_deps = departments.filter(function(dep) {
if (dep.description && dep.description.includes('English')) {
return dep;
}
});
} else {
var new_deps = departments.filter(function(dep) {
if (dep.description && dep.description.includes('French')){
return dep;
}
});
}
//modify the department array by reference
departments.length=0; //empty the array
console.log("new_deps",new_deps);
new_deps.forEach(function(d) { //populate the department array
departments.push(d);
});
});
</script>

onNewConversationComponentInit

This event is generated as soon as a new conversation view is rendered. Use this event if you want to execute some actions on a Conversation start.

Important payload of event_data:

Property	Type	Description
detail.newConvId	Object	the id of the conversation that fired the event

Example:

In the following example a hidden message is sent as soon as a conversation starts. Sending a hidden message is useful to fire a bot welcome message, if one is invited in the conversation.

<script type="application/javascript">
window.Pingstreams('onNewConversationComponentInit', function(event_data) {
const message = 'hello';
const recipientId = event_data.detail.newConvId;
const recipientFullname = 'Owner';
const type = 'text';
const metadata = {};
const attributes = {test:'test attributes', subtype: 'info'};
window.pingstreams.sendSupportMessage(
message,
recipientId,
recipientFullname,
type,
metadata,
attributes
)
});
</script>

onMessageCreated

This event is generated when the widget receive a message.

Important payload of event_data:

Property	Type	Description
detail	Object	the message that was received

Example:

<script type="application/javascript">
window.Pingstreams('onMessageCreated', function(event_data) {
var message = event_data.detail;
console.log("TRIGGER onMessageCreated -> ", message);
});
</script>

onConversationUpdated

This event is generated when the widget receive a conversation update.

Important payload of event_data:

Property	Type	Description
detail	Object	the conversation that was received

Example:

<script type="application/javascript">
var now = Date.now();
window.Pingstreams('onConversationUpdated', function(event_data) {
var dateConvUpdate = event_data.detail.conversation.timestamp
console.log(" TRIGGER onConversationUpdated -> ", event_data.detail.conversation);
console.log("now-> ", now);
console.log("dateConvUpdate-> ", dateConvUpdate);
if(now < dateConvUpdate){
console.log(" New conversation!!!");
}
});
</script>