Appearance
Pleased Widget Config
This interface provides several options to customize the behavior of the chat widget according to your application's needs.
Properties
metaTags
This is an optional record that contains key-value pairs. These pairs are used as system tags in Pleased for the tickets/chats created by the user.
Here's an example of how to use this command:
js
window.pLS('set:config', {
metaTags: {
query: 'deposits',
user_tier: 'premium',
},
});locale
This is an optional string that specifies the default language to load the chatbot in. If not specified, the chatbot will load in English.
Here's an example of how to use this command:
js
window.pLS('set:config', {
locale: 'es',
});loginMethod
This is an optional string that specifies the login method. It can be 'external', 'hybrid', or 'none'. By default, it is 'none'. Learn more how to use it in your login strategy
'external'login refers to a login method where the client prefers to use their own login screen instead of inputting username/password information on the Pleased screen. On the chatbot side, a Login button is shown; tapping it emits therequest_loginevent so the host app can open the client’s login flow. After external login completes successfully on your side, runpLS('widget:re_auth')so the widget re-authenticates with the new session (see Chatbot authentication in the Widget API guide).'hybrid'login refers to a method where logins can take place via the Pleased chatbot. Users input their credentials through the chatbot, which then forwards these credentials to the client. The handler for this method can be set viapLS('set:callback', { login: ({username, password}) => Promise.resolve() }).The client must provide an additional widget login page whose response body carries the same kind of auth and user payload as other integrations (including
tokenand user fields). The payload should match this shape:typescriptexport interface LoginResult { token: string; bizCode: string | number; }Set
bizCodeto10000for a successful login; any other value indicates an error.'none'supports only the guest user flow: there is no login. Users are not prompted to authenticate.
Here's an example of how to use this command:
js
window.pLS('set:config', {
loginMethod: 'hybrid',
});loginUserNameType
This is an optional string that specifies the login identifier type in the app. It can be 'phone' or 'email', and determines which identifier the login form asks for and validates.
'username'is accepted by the type but not supported: the widget has no username input or validation, so it is ignored and the form keeps its previous type. Use'phone'or'email'.
Here's an example of how to use this command:
js
window.pLS('set:config', {
loginUserNameType: 'email',
});uiConfig
This is an optional object that provides configuration options for the user interface (UI) of the application.
Here's an example of how to use this command:
js
window.pLS('set:config', {
uiConfig: {
header: {
show: true,
},
bubble: {
show: true,
},
},
});header
- show: An optional boolean. When
false, hides the header on the Help, Article, and Conversations list pages (overrides brand customisation there). Defaults totrue, in which case header visibility on those pages is controlled by brand customisation settings. It does not affect the in-chat (Chatroom) header or the Home page header, neither of which currently read this field.
bubble
- show: An optional boolean property that determines whether to display the bubble button when the widget is collapsed. Defaults to
true.
appVersion
An optional string identifying the version of your application. The widget includes it in new chats, calls, and open-request tickets, including guest requests. Agents see it in the customer panel.
Set it before starting a chat, call, or open request:
js
window.pLS('set:config', { appVersion: '5.12.0' });Runtime updates apply to subsequent creations. They do not update existing chats, calls, or tickets.
To clear the version for subsequent creations:
js
window.pLS('set:config', { appVersion: '' });If no version has been provided, the field remains blank. Omitting appVersion from a partial config update preserves its current value.
persistChatSession
An optional boolean, false by default. When true, a visitor with an active live chat stays connected to it after a page reload or navigation in the same browser tab, even while the widget is closed:
unread_messageskeeps counting agent messages.- The visitor shows as online to the agent.
- Opening the widget goes straight back into the chat, without the "Continue your last chat" prompt.
A new tab or a later visit still shows the prompt. When the flag is off, the widget behaves as before: the chat reconnects only after the visitor opens the widget and continues the conversation.
js
window.pLS('set:config', { persistChatSession: true });Inline placement (data-pls-container-id)
By default the widget mounts a floating launcher into document.body. To render the widget inline inside an element you control (for example an in-app preview), add data-pls-container-id to the loader script, pointing at the id of a container that already exists in the DOM:
html
<div id="my-widget-host" style="position: relative; width: 342px; height: 500px;"></div>
<script
src="pl-loader.min.js"
data-pls-client-id="YOUR_CLIENT_ID"
data-pls-widget-id="YOUR_WIDGET_ID"
data-pls-container-id="my-widget-host"
></script>In this mode the widget fills the host container (no floating bubble, no position: fixed) and opens automatically. If the container element is not found when the script runs, the loader emits an error event. Omit data-pls-container-id for the normal floating behavior.
data-pls-widget-id accepts the UUID shown on newly created widget configurations. Legacy numeric widget IDs remain supported for existing integrations.
Teardown (widget:destroy)
See Destroying the Widget in the Widget API guide.