Web Controls

Once the widget script has loaded, Chatleadr puts a small API on window so your own buttons and links can drive the chat.

The window.Chatleadr API#

Wait for chatleadr-ready#

window.Chatleadr is defined when the widget mounts. Calling a method before then throws a TypeError, because the object does not exist yet.

The widget fires a chatleadr-ready event on window when the API is available.

<script>
  window.addEventListener('chatleadr-ready', function () {
    document.querySelector('#help-button').addEventListener('click', function () {
      window.Chatleadr.open();
    });
  });
</script>

Starting a Conversation With a Message#

sendMessage opens the chat and submits text on the visitor's behalf, so a button can drop someone into the middle of a conversation instead of at the start of one.

<button type="button" id="ask-delivery">Ask About Delivery</button>

<script>
  whenReady(function () {
    document.querySelector('#ask-delivery').addEventListener('click', function () {
      window.Chatleadr.sendMessage('How long does delivery take to Bloemfontein?');
    });
  });
</script>

The message is treated exactly as if the visitor typed it, so it goes through normal workflow matching. Word the message as a question. Workflow selection reads each workflow's description against the visitor's message, so a command such as "delivery info" gives it less to match on.

Product Page Example#

A per-product enquiry button, with the product name interpolated server-side:

<button type="button" class="cl-ask" data-product="6-Seater Patio Set">
  Ask About This Product
</button>

<script>
  whenReady(function () {
    document.querySelectorAll('.cl-ask').forEach(function (btn) {
      btn.addEventListener('click', function () {
        window.Chatleadr.sendMessage(
          'I have a question about the ' + btn.dataset.product + '.'
        );
      });
    });
  });
</script>

Configuration Globals#

Set by the install snippet, before the widget script loads. They are read once at startup; changing them later has no effect.

The install snippet that sets both is on install on any website.

Local Storage#

The widget keeps two keys per bot so a visitor moving between pages stays in the same conversation.

After ten minutes with no interaction the widget discards the cached session and starts a fresh one, using the same ten-minute window described in what counts as a conversation. Clearing these keys resets the visitor to a new conversation, which is useful when testing.

What the API Covers#

The API opens, closes and toggles the panel and sends a message, and chatleadr-ready is the only event it emits. To request prefilling the input without sending it, or setting visitor identity from the page, email support@chatleadr.com describing what you are building.

Common Questions#

Can I Hide the Default Launcher and Use My Own Button?#

The widget renders inside a shadow root on #chatleadr-widget-app, so page CSS cannot reach the launcher, and hiding that element hides the chat panel with it. Drive the panel from your own button with open(), close() and toggle(), and leave the launcher where it is.

Does sendMessage Start a Billed Conversation?#

Yes. It is treated exactly as a visitor message, so it starts a conversation if one is not already active. A button that fires it on page load instead of on click will start a new billed conversation on every visit that falls outside the ten-minute session window.

Can I Read the Conversation From the Page?#

No. There is no event stream and no transcript API on the widget. Conversations are available in the dashboard, and lead data can be pushed out by a workflow through an API node or a ClickUp integration.

Does the API Work on a Single-Page App?#

Yes. window.Chatleadr stays available across client-side navigations. See install on any website for where the snippet goes in a single-page app.

Related#

• Install on any website
• Widget appearance
• Capture leads from your website
• What counts as a conversation