Chat

Add chat to your website

Put an assistant on your site with one script tag, lock it to your domain, and wire its events into your analytics.

The chat widget is a launcher and a chat panel your visitors open from any page. It loads in two steps so it stays out of the way: a small loader script (about 14 KB before compression) shows the launcher, and the chat itself loads only when a visitor shows intent, like hovering or clicking.

Turn on web chat and allow your domain

The assistant needs channels.web_chat.enabled and the origins it may be used from. List every origin your site is served on, with scheme and port where it isn't the default; there are no wildcards.

config.channels.web_chat

{
  "enabled": true,
  "allowed_origins": ["https://www.acmetravel.com", "https://acmetravel.com"],
  "greeting": "Hi! Planning a trip? I can help."
}

Send it with PATCH/api/assistants/{id}. A config in a PATCH replaces the whole config, so send the full object you read with GET/api/assistants/{id}, changed. Values the API never returns (secrets, tool request specs) are kept for the objects and tools you send back, and leaving knowledge out keeps the stored selection.

Get a publishable key

Create one with POST/api/publishable-keys and {"assistant_id": "asst_..."}, or in the console under Channels > Web chat, which also copies the snippet for you. Authentication explains why this key is safe in page source.

Add the script

Paste this before </body> on every page that should show the chat:

HTML

<script
  async
  src="https://api.myleadsfactory.tech/widget/v1/loader.js"
  data-mlf-key="pk_live_4b1f0c9e2a7d4e6b8c3f5a1d9e0b7c62"
></script>

That's the whole integration. Reload the page and the launcher appears at the bottom right.

Script attributes

Attribute	Required	What it does
`data-mlf-key`	Yes	Your publishable key
`data-mlf-assistant`	With project keys	The assistant to chat with, when the key is for a whole project
`data-mlf-launcher="none"`	No	Hides the built-in launcher so you can open the chat from your own button

Control it from your page

Once the loader runs, window.mlf is defined:

JavaScript

mlf.open()       // open the panel
mlf.close()
mlf.toggle()
mlf.preload()    // load the chat now (for example on hover of your own button), without opening it
mlf.hide()       // remove launcher and panel, for checkout or signing flows
mlf.show()       // undo hide()
mlf.setContext({ plan: 'pro', utm_source: 'google' }) // stored on the next conversation's metadata
mlf.setConsent(true) // release analytics events held until consent

With data-mlf-launcher="none", wire your own button to mlf.open().

Listen to what happens

Every event reaches mlf.on(name, handler) and is also dispatched on window as mlf:<name>, so analytics needs no SDK:

Event	When
`ready`	The configuration loaded and the launcher is showing
`open`, `close`	The panel opened or closed; `open` carries `{ reason }`: `visitor`, `proactive` or `api`
`unread`	The unread count changed (`{ count }`)
`conversation:started`	The visitor sent their first message (`{ conversation_id }`)
`message:sent`, `message:received`	A visitor turn completed
`handoff:requested`	The assistant asked for a person to follow up
`call:clicked`	The visitor tapped the call link in the header

JavaScript

window.addEventListener('mlf:conversation:started', (e) => {
  dataLayer.push({ event: 'chat_started', conversation_id: e.detail.conversation_id })
})

A conversation exists only once the visitor sends a message. Opening the panel and leaving creates nothing, so every conversation you see is a real exchange.

Next.js and single-page apps

Load the script once in your root layout with next/script and strategy="afterInteractive", rather than on each page, so client-side navigation does not load it twice.

app/layout.tsx

import Script from 'next/script'

<Script
  src="https://api.myleadsfactory.tech/widget/v1/loader.js"
  data-mlf-key={process.env.NEXT_PUBLIC_MLF_CHAT_KEY}
  strategy="afterInteractive"
/>

Content Security Policy

If your site sends a CSP header, allow the API origin for the loader, its configuration request and the chat frame:

CSP

script-src  https://api.myleadsfactory.tech;
connect-src https://api.myleadsfactory.tech;
frame-src   https://api.myleadsfactory.tech;

When the launcher does not appear

The key is wrong or revoked, or web chat is off for the assistant: the configuration request answers 404 and the loader stays hidden.
Your origin is not allowed: the browser console shows the configuration request refused. Add the exact origin, including www. if you use it.
It is hidden: check for an earlier mlf.hide() call.

To build the chat interface yourself instead of using the widget, see Build your own chat UI. Two settings are for your own interface: a lead panel that shows the visitor what they have shared, and voice in the same conversation.