Appearance
Pleased Widget Events
The Pleased Widget is a powerful tool for integrating a chatbot into your website. It provides a variety of events that you can listen to, allowing you to create a more interactive and responsive user experience. This document will guide you through the different events that the Pleased Widget exposes.
Event Types
The Pleased Widget exposes the following events:
readyopencloserequest_loginratingunread_messageserroropen_request_createdon_chat:starton_chat:endchat_sessionrequest_open_settings
ready
The ready event is triggered when the chatbot is fully loaded and ready to interact with the user. This event does not carry any data.
Example usage:
javascript
window.pLS('event:on', 'ready', () => {
console.log('Chatbot is ready');
});open
The open event is triggered when the chatbot window is opened by the user. This event does not carry any data.
Example usage:
javascript
window.pLS('event:on', 'open', () => {
console.log('Chatbot window opened');
});close
The close event is triggered when the chatbot window is closed by the user. This event does not carry any data.
Example usage:
javascript
window.pLS('event:on', 'close', () => {
console.log('Chatbot window closed');
});request_login
This event is triggered when the user requests to log in. This could be because they clicked on the Login button in the header, or on the login page. You can trigger your application's login flow here. It does not carry any data.
Example usage:
javascript
window.pLS('event:on', 'request_login', () => {
console.log('Login requested');
// Trigger your app's login flow here
});rating
The rating event is triggered when the user rates their experience with the connected agent. This event carries a number data representing the rating given by the user. This can be used to show popup on rate the app in Play Store.
Example usage:
javascript
window.pLS('event:on', 'rating', (rating) => {
console.log(`User rated the chatbot: ${rating}`);
});unread_messages
The unread_messages event is triggered when there are unread messages in the chatbot. This event carries a number data representing the count of unread messages.
Example usage:
javascript
window.pLS('event:on', 'unread_messages', (count) => {
console.log(`There are ${count} unread messages`);
});error
The error event is triggered when there is an error in the chatbot. This event carries an unknown data representing the error.
Example usage:
javascript
window.pLS('event:on', 'error', (error) => {
console.log(`An error occurred: ${error}`);
});open_request_created
The open_request_created event is fired once each time a visitor successfully creates an open request in the chatbot (logged-in, guest OTP, or chat-trigger flows). Use it to react on your side, for example analytics or a redirect.
The event carries an object with the following fields:
| Field | Type | Description |
|---|---|---|
id | number | ID of the created request |
subject | string | Subject of the created request |
isCreated | boolean | true if a new request was created; false if matched to an existing one |
description | string (optional) | Description the visitor provided, when available |
recipientAddress | string (optional) | Email the request will be sent to, when available |
chatbotSessionId | string (optional) | Chatbot analytics session id, when available |
Example usage:
javascript
window.pLS('event:on', 'open_request_created', (data) => {
console.log(`Open request #${data.id}: ${data.subject}`);
if (data.isCreated) {
console.log('New request created');
}
});on_chat:start
The on_chat:start event is fired each time a live (with agent) chat session becomes active in the widget. This tracks the live-chat session, not the widget window — use open / close for window state. It does not wait for an agent to join.
Example usage:
javascript
window.pLS('event:on', 'on_chat:start', () => {
console.log('Live chat session started');
});on_chat:end
The on_chat:end event is fired when the visitor ends a live chat session: after they confirm "End chat", or after 30 minutes without visitor activity (text message, file upload, or typing). It is not fired when an agent ends the chat, and not when the visitor only closes or minimizes the widget. Closing the widget without ending the chat can therefore leave an on_chat:start without a matching on_chat:end.
Example usage:
javascript
window.pLS('event:on', 'on_chat:end', () => {
console.log('Live chat session ended');
});chat_session
The chat_session event fires when the visitor gains or loses a live/resumable chat session — the same notion as get:has_chat_session. The handler receives a boolean: true when a session exists, false when it does not.
If you subscribe after the value is already known, you will not receive the current value until it changes; use await window.pLS('get:has_chat_session') for an immediate read.
Example usage:
javascript
window.pLS('event:on', 'chat_session', (hasSession) => {
console.log('Visitor has a chat session:', hasSession);
});request_open_settings
Native apps only. Fired when a voice call needs the microphone and the OS has blocked it; open your app's settings screen. Sent only if you declared canOpenAppSettings — see When the microphone is blocked (Android) or iOS.
Event Commands
The Pleased Widget exposes three different commands for handling events:
event:onevent:offevent:once
event:on
The event:on command is used to register a handler function that will be called every time the specified event is triggered.
event:off
The event:off command is used to remove a previously registered handler function from the specified event.
Pass the same function you registered — keep a reference to it. An inline arrow function cannot be removed, because a new one is never equal to the old. This works for handlers added with event:on and for event:once handlers that have not fired yet.
javascript
const onClose = () => console.log('Chat closed');
window.pLS('event:on', 'close', onClose);
// later
window.pLS('event:off', 'close', onClose);event:once
The event:once command is used to register a handler function that will be called only the first time the specified event is triggered.