Skip to content

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:

  1. ready
  2. open
  3. close
  4. request_login
  5. rating
  6. unread_messages
  7. error
  8. open_request_created
  9. on_chat:start
  10. on_chat:end
  11. chat_session
  12. request_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:

FieldTypeDescription
idnumberID of the created request
subjectstringSubject of the created request
isCreatedbooleantrue if a new request was created; false if matched to an existing one
descriptionstring (optional)Description the visitor provided, when available
recipientAddressstring (optional)Email the request will be sent to, when available
chatbotSessionIdstring (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:

  1. event:on
  2. event:off
  3. event: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.