Chat widget v3 integration

Chat widget v3 is a rebuilt widget that loads a different script and is initialised with ChatWidget.init() instead of window.ymConfig. If your bot is on widget v3 (Channels > Chat widget, widget version New), the v2 integration snippets and window.YellowMessengerPlugin APIs do not apply — use this page instead.

In this article, you will learn:

How to install the widget
Configuration options
Methods you can call
URL parameters
What changed from v2

Channels > Chat widget > Deploy gives you the snippet for your bot. Paste it before the closing </body> tag:

<script type="text/javascript">
  (function () {
    var e = document.createElement("script");
    e.src = "https://cdn.yellowmessenger.com/plugin/widget-v3/prod/dist/loader.umd.js";
    e.async = !0;
    e.onload = function () {
      ChatWidget.init({
        yellowMessenger: {
          botId: "x1657623696077",
          host: "https://cloud.yellow.ai"
        }
      });
    };
    document.head.appendChild(e);
  })();
</script>

botId and host are required. host must be the region host for your bot — the Deploy screen fills in the right one.

note

The script must finish loading before ChatWidget exists, which is why the snippet calls init() from onload. Calling ChatWidget.init() from a script that runs earlier will fail with ChatWidget is not defined.

2. Configuration options

init() takes a single object. Connection settings go inside yellowMessenger; presentation settings sit at the top level.

2.1 Inside `yellowMessenger`

Option	Type	Description
`botId`	string	Required. Your bot ID.
`host`	string	Required. Region host, for example `https://cloud.yellow.ai`.
`payload`	object	Data passed from your page to the bot. See Chat widget payload.
`ymAuthenticationToken`	string	JWT for authenticated users. See User authentication.
`autoOpen`	boolean	Open the chat panel as soon as the widget loads.
`defaultOpenMode`	`"chat"` \| `"voice"`	Which panel opens when the user opens the widget without typing. Defaults to chat.
`pwa`	boolean	Standalone page mode — no floating launcher, panel open on mount, centred at 80% of the viewport.
`fullScreen`	boolean	Edge-to-edge instead of the centred PWA look. Below 768px the widget is always full-bleed.
`trigger`	string	Entry point to start on, in `kind:slug` form.
`triggerJourney`	string \| boolean	Journey to trigger on load.

2.2 Top level

Option	Type	Description
`placement`	`"left"` \| `"right"`	Which side the launcher sits on. Defaults to `right`. Any other value throws.
`defaultExpandedState`	boolean	Whether the panel starts expanded.
`onClose`	function	Called when the user closes the panel.

ChatWidget.init({
  yellowMessenger: {
    botId: "x1657623696077",
    host: "https://cloud.yellow.ai",
    autoOpen: true,
    defaultOpenMode: "chat"
  },
  placement: "left",
  onClose: function () {
    console.log("widget closed");
  }
});

native mobile apps

sdk, appId, handlers and deviceToken switch the loader into SDK mode for native app embeds. They are not needed for a website integration — see the Android and iOS pages.

3. Methods

ChatWidget exposes four methods.

Method	Description
`ChatWidget.init(options)`	Loads and mounts the widget. No-op if the widget is already on the page — see the note below.
`ChatWidget.destroy()`	Removes the widget, its launcher and its listeners from the page.
`ChatWidget.open(message?, view?)`	Opens the panel. Pass `message` to send it as the user's first message; pass `view` (`"chat"`, `"voice"`, `"history"` or `"knowledge_base"`) to choose the panel.
`ChatWidget.sendEvent(name, data?)`	Sends a custom event into the conversation. Forwarding is gated by the bot's `acceptEventFromClient` widget setting — if that is off, the event is dropped.

Trigger the widget from your own button instead of the built-in launcher:

document.getElementById("my-chat-button").addEventListener("click", function () {
  window.ChatWidget.open();
});

init() does not re-initialise

init() returns without doing anything if the widget is already mounted, so you cannot call it a second time to apply new options. To apply a new configuration — a payload for a user who just signed in, for example — call ChatWidget.destroy() first and then init() again. That starts a new session: the existing conversation is not carried over.

4. URL parameters

The loader reads these query parameters from the page URL and merges them into the yellowMessenger config, which is useful for shared links and PWA pages:

Parameter	Maps to
`ym.bot`	`botId`
`ym.payload`	`payload`
`ym.trigger`	`trigger`
`ym.triggerJourney`	`triggerJourney`
`ymAuthenticationToken`	`ymAuthenticationToken`

A URL parameter overrides the value passed to init(), and ym.bot means botId can be omitted from the snippet.

caution

Anything in a URL is visible to the user and is logged by proxies and analytics. Do not put personal data in ym.payload, and prefer passing it to init().

5. What changed from v2

	Chat widget v2	Chat widget v3
Script	`.../plugin/widget-v2/latest/dist/main.min.js`	`.../plugin/widget-v3/prod/dist/loader.umd.js`
Configuration	`window.ymConfig`	`ChatWidget.init({ yellowMessenger: … })`
Global	`window.YellowMessengerPlugin`	`window.ChatWidget`
Re-initialise with new config	`YellowMessengerPlugin.init({ … })`	Not supported — `destroy()` then `init()`, which starts a new session
Open the widget	`YellowMessengerPlugin.openBot()` / `show()`	`ChatWidget.open()`
Close / hide the widget	`closeBot()`, `hide()`, `toggleChat()`	No equivalent — `destroy()` removes the widget entirely
Remove the widget	—	`ChatWidget.destroy()`
Close callback	Listen for the `bot-closed` event	`onClose` option

The v2 pages on function widgets and widget events describe window.YellowMessengerPlugin and the v2 event names. Neither applies to a v3 widget.

1. Install the widget​

2. Configuration options​

2.1 Inside yellowMessenger​

2.2 Top level​

3. Methods​

4. URL parameters​

5. What changed from v2​

1. Install the widget