Skip to content

Pleased Chatbot API User Guide ​

Welcome to the Pleased Chatbot API User Guide. This guide will help you understand how to control the Pleased Chatbot using the window.pLS() function.

Command
widget:open, widget:closeOpening, Closing
widget:re_authChatbot authentication
widget:destroyTeardown
chat:endEnding a Live Chat
get:is_ready, get:is_chatting, get:is_openInitialized, Live Chat; get:is_open — whether the widget is open
get:has_chat_sessionChat to return to — live or resumable chat. Must be awaited
set:config, set:locale, set:visitorStartup Options, Locale, Visitor
set:callback token / loginAuthenticated Users, Login Callback
event:on, event:once, event:offEvent Handling, Widget Events

From a native app, see Android: bridge reference or iOS: bridge reference.

Opening the Chatbot ​

To open the chatbot, use the widget:open command.

javascript
window.pLS('widget:open');

Closing the Chatbot ​

To close the chatbot, use the widget:close command.

javascript
window.pLS('widget:close');

Destroying the Widget ​

To remove the widget from the DOM and reset the loader, use the widget:destroy command. This removes the iframe, styles and listeners. After it runs you can inject the loader script again (for example to load a different widget) and it will re-initialize cleanly.

javascript
window.pLS('widget:destroy');

Ending a Live Chat ​

To end the current live agent chat session, use the chat:end command. It requires no parameters. The command is accepted while the widget is minimized: the live session still ends in the background.

The call does not return a result. Use get:is_chatting or event:on with on_chat:end if the host needs to observe whether the session ended. If no live chat is active, the command does nothing and does not create a new conversation.

javascript
window.pLS('chat:end');

Chatbot authentication. ​

If a user logs in or out from your website, you can trigger the widget:re_auth command to re-authenticate the Pleased Widget.

javascript
window.pLS('widget:re_auth');

Checking if the Chatbot is Initialized ​

To check if the chatbot is initialized, use the get:is_ready command.

javascript
window.pLS('get:is_ready');

Checking if the Visitor is in a Live Chat ​

To check whether the visitor is currently in a live (agent) chat, use the get:is_chatting command. It tracks the live-chat session itself, not the widget window — so it stays true while a chat is ongoing even if the visitor closes the widget. It returns true during an active agent chat session, and false before the widget is ready and during a bot-only conversation.

javascript
window.pLS('get:is_chatting');

Checking if the Visitor Has a Chat Session to Return To ​

To learn whether the visitor has a live agent chat in progress or an open chat they can resume (without opening the widget), use get:has_chat_session. This is separate from get:is_chatting, which is only true while a live chat is actively running in the widget.

You must await this command. It returns a Promise (unlike the other getters).

javascript
const hasSession = await window.pLS('get:has_chat_session');

If you call it before the widget has finished loading, it waits until the widget is ready and then answers. You can also listen for changes with the chat_session event.

Checking if the Chatbot is Open ​

To check whether the chat panel is currently open (maximized), use the get:is_open command.

javascript
window.pLS('get:is_open');

Setting Startup Options ​

To pass options to the chatbot, use the set:config command. For the available options, see Widget Config.

javascript
window.pLS('set:config', { loginMethod: 'external' });

Setting the Locale ​

To set the locale of the chatbot, use the set:config command. The supported locales are 'en', 'pt-br'.

javascript
window.pLS('set:config', { locale: 'en' });

Setting Visitor Details ​

To set the visitor details for the chatbot, use the set:visitor command. A partial payload merges into the visitor already set — fields you omit are left untouched.

javascript
window.pLS('set:visitor', { name: 'your_name', phone: 'your_phone', email: 'your_email', foreignId: 'client-user-id' });

// Merges into the existing visitor — only updates the fields given.
window.pLS('set:visitor', { email: 'new_email@example.com' });

Pass null to clear the name/email/phone/foreign id override set:visitor applied. For a guest, this resets those fields on their session (the session itself — the visitor's token and whether they've already filled in their details — is preserved, not logged out). For an authenticated user, it removes the override entirely, so the visitor's name/email/phone/foreign id simply revert to their real authenticated profile values rather than becoming empty.

javascript
window.pLS('set:visitor', null);

Enabling Authenticated Users ​

To enable authenticated users on the chatbot, use the set:callback command. This will enable the Pleased Client to identify users & their previous requests.

javascript
window.pLS('set:callback', { token: async () => generateTokenFromApi() });

Registering the Login Callback ​

To register the login callback, use the set:callback command again. This callback can be used to authenticate the given user.

javascript
window.pLS('set:callback', { login: async ({ username, password }) => loginUser() });

Event Handling ​

To register event handlers for the chatbot, use the event:on, event:off, or event:once commands. For more details on ChatbotEvents, please refer to Widget Events.

javascript
window.pLS('event:on', 'open', your_handler);
window.pLS('event:once', 'rating', your_handler);

// Removing: event:off with the same function reference you registered.
window.pLS('event:off', 'open', your_handler);

We hope this guide helps you to control the Pleased Chatbot effectively. If you have any questions, feel free to reach out to us.