Skip to content

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 the request_login event so the host app can open the client’s login flow. After external login completes successfully on your side, run pLS('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 via pLS('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 token and user fields). The payload should match this shape:

    typescript
    export interface LoginResult {
      token: string;
      bizCode: string | number;
    }

    Set bizCode to 10000 for 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,
    },
  },
});
  • show: An optional boolean. When false, hides the header on the Help, Article, and Conversations list pages (overrides brand customisation there). Defaults to true, 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_messages keeps 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.