The widget exposes a small JavaScript API so you can open the chat from your own buttons, links or product tours instead of waiting for someone to click the launcher.
Why open the chat programmatically
The launcher button handles most situations fine, but sometimes you want the chat panel to appear at the right moment — after someone reads a pricing page, fills in a form, or spends a while on a help article without finding what they need. Opening programmatically means your site decides when to surface the conversation, not just the visitor.
Common use cases:
- A "Talk to us" button in your own UI that matches your design system instead of floating over it
- A product tour step that ends with "Got questions? Chat with us"
- A form confirmation page that opens the chat so someone can follow up
- A timed prompt after the visitor spends 60 seconds on a high-intent page without converting
Prerequisites
You need the widget embed snippet on the page. Grab it from your agent's Deploy tab — it looks like this:
<script
src="https://chattering.ai/widget.js"
data-chattering="YOUR_AGENT_ID"
async
></script>
Paste it before the closing </body> tag on any page where you want the widget. Once the script loads, window.Chattering is available automatically — there is nothing extra to initialise.
The open method
window.Chattering.open()
Calling this opens the chat panel. If the panel is already open, the call does nothing — it will not double-open or flicker. If the widget has not finished loading when you call it, the call is queued and fires automatically once the panel is ready.
The full set of methods the widget exposes:
| Method | What it does |
|---|---|
window.Chattering.open() |
Opens the chat panel |
window.Chattering.close() |
Closes it |
window.Chattering.toggle() |
Opens if closed, closes if open |
window.Chattering.identify(id, data) |
Links this session to a known contact |
window.Chattering.track(name, data) |
Sends a product event to the contact timeline |
window.Chattering.clearIdentity() |
Forgets the current identity on logout |
open() takes no arguments. There is no option to pre-fill the input or force a specific panel section.
Code examples
Open on page load
If you want the chat to open as soon as the page is ready, use the pre-load stub so early calls are not lost:
window.Chattering = window.Chattering || { _q: [] };
['open', 'close', 'toggle'].forEach(function (m) {
window.Chattering[m] = window.Chattering[m] ||
function () {
window.Chattering._q.push([m, [].slice.call(arguments)]);
};
});
window.Chattering.open();
The stub queues the call if the widget has not loaded yet. Once the script finishes building the panel, it replays anything in _q and the panel opens. Drop this after your embed script tag.
Open on button click
const button = document.querySelector('#chat-with-us');
button.addEventListener('click', function () {
window.Chattering.open();
});
Give any button on your page the id chat-with-us and clicking it opens the chat. You can use any valid CSS selector — the id is just an example.
Open after a timed delay
setTimeout(function () {
window.Chattering.open();
}, 60000);
This opens the panel 60 seconds after the page loads. Useful on high-intent pages where a prompt after a short wait often converts — pricing comparisons, long help articles, or checkout flows where the visitor has clearly been reading but has not acted.
Browser compatibility
window.Chattering.open() works in all modern browsers: Chrome, Firefox, Safari, and Edge on both desktop and mobile. JavaScript must be enabled. No polyfills are required. The widget's internal code avoids arrow functions and modern syntax features so it runs in environments where your own build tools might not, but there is no support for Internet Explorer.
Troubleshooting
Calling window.Chattering.open() does nothing
Check that the embed script has actually loaded. Run console.log(window.Chattering) in the browser console — if it prints undefined, the script tag is missing or blocked. View source and confirm the script tag is present with your agent's public ID in data-chattering. A Content Security Policy that blocks chattering.ai is the most common cause of a silent failure — add chattering.ai to your script-src and connect-src directives.
The object exists but open() silently does nothing
If window.Chattering is present but the call is a no-op, the widget object is the pre-load stub rather than the real API. Use the queuing stub shown in the page-load example so calls fire after the panel is built.
The chat opens once but stops responding after navigating
Single-page apps re-render the DOM without reloading the script. If your framework removes the widget's launcher div on a route change, the widget detects the missing DOM on the next call and re-initialises. If the script itself is not re-injected after the route change, call the open method before any navigation that removes the launcher.
The agent loads but gives no replies
If the panel opens and accepts a message but the AI does not respond, check that the agent is active. Go to Agents in your Chattering dashboard and confirm the agent tied to your public ID is switched on and has at least one indexed source.