Appearance
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:close | Opening, Closing |
widget:re_auth | Chatbot authentication |
widget:destroy | Teardown |
chat:end | Ending a Live Chat |
get:is_ready, get:is_chatting, get:is_open | Initialized, Live Chat; get:is_open — whether the widget is open |
get:has_chat_session | Chat to return to — live or resumable chat. Must be awaited |
set:config, set:locale, set:visitor | Startup Options, Locale, Visitor |
set:callback token / login | Authenticated Users, Login Callback |
event:on, event:once, event:off | Event 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.