Widget behavior and JavaScript API

The loader you install is a small script that draws the launcher and manages the chat frame. This page explains what it does on the page and the small JavaScript API it exposes.

What the loader does

1. Reads its configuration from its own script tag: data-organization-id, data-position and data-preload. If the tag was injected by a tag manager and the attributes cannot be read directly, it looks for the first script on the page whose source contains widget and has a data-organization-id.
2. Draws the launcher button in the chosen corner once the page's content has loaded.
3. Unless preloading is off, loads the chat frame in the background during idle time so the first click opens instantly.
4. Opens and closes the frame when the launcher is clicked, and listens for the close message the chat sends when a visitor taps the X inside it.

If the same page contains two snippets, the second logs "already initialized" and does nothing, so you never get two launchers. Without a data-organization-id the loader logs an error and stops.

The launcher and the window

• The launcher is a 60-pixel round button 20 pixels from the bottom and from the chosen side. Its color is fixed; the brand color you set in Widget Customization styles the chat window itself, not the button.
• The chat window is 400 by 600 pixels and shrinks to fit small screens. It opens above the launcher with a short fade.
• If the chat frame has not loaded 15 seconds after a visitor opens it, the window shows "The chat couldn't load" with a hint to check the connection. Reloading the page starts over.

Positions

data-position accepts bottom-right (default) and bottom-left. Any other value falls back to bottom right and logs a warning.

Preloading

data-preload defaults to true. With preload on, the chat frame is fetched during idle time after your page has finished loading, so the widget opens immediately on the first click. A preloaded widget only reads your workspace settings; a visitor session is created only when the window is actually opened, so visitors who never use the chat never create one. Set data-preload="false" to fetch the frame only on the first click.

Inside the window

The window has three tabs at the bottom: Home, Messages (the visitor's past conversations in this browser) and Help (your published Help Center articles). The Help tab disappears when you turn it off or when you have no published articles.

Home shows your welcome headline and subline, a Send us a message card, and, if you have published articles, a help search with your top four articles. Voice and phone buttons appear when you have configured them.

When a workspace has no published articles, Home switches to a chat-first layout: a compact header with your assistant name and "AI assistant · online", your greeting as the first message, your suggested questions as tappable chips, and a composer. Typing a message or tapping a chip starts the conversation immediately. Without configured suggestions the chips read "What can you help me with?", "How do I get started?" and "I'd like to talk to a person".

Everything on these screens is controlled from Widget Customization.

JavaScript API

After the loader runs, window.EchoWidget is available with four methods.

<button onclick="window.EchoWidget && window.EchoWidget.show()">
  Chat with us
</button>

The API exists only once the loader has executed. If your code may run earlier, check for window.EchoWidget first, as in the example.

Sessions and storage

• Chats start anonymous. There is no pre-chat form; a visitor is simply "Visitor" until they verify an email.
• The widget sets no cookies on your site. It keeps the visitor's session ID in its own browser storage, so Messages shows that browser's conversations only.
• A session lasts 24 hours and is extended while the visitor keeps chatting. After it expires a fresh anonymous session starts and the Messages list is empty again. Conversations themselves stay in your team inbox.

Messages visitors may see