Triggering the Widget Programmatically
Last updated: October 26, 2026
By default the Docket widget appears on its own, using the rules set for each domain. If you would rather open it from a "Talk to Sales" button, a form submission, or a link in your own interface, you can switch the widget to click-only and drive it from JavaScript.
There are two halves to this: an agent setting that stops the widget opening by itself, and a method call that opens it when you want.
What do you need before you start?
The Docket widget script installed on your website.
The domain added to the agent's Whitelist Domains list. Widget behavior is set per domain, so the domain has to exist before you can choose how it behaves.
Your trigger code running only after the Docket script has loaded.
How do you stop the widget opening on its own?
Widget behavior lives on the Widget tab and is configured separately for each whitelisted domain. If the section looks empty, add a domain under Whitelist Domains first: until then Docket shows "Add at least one domain to the whitelist to get started" and there is nothing to configure.
Sign in to app.docketai.com and open Marketing Agent Configuration.
Select your agent, then open the Widget tab.
Open Widget Behaviour with the chevron.
Find the card for the domain you are configuring.
Under Show Widget on, select On Click (Function Call).
Select Save.

Each domain keeps its own setting, so you can leave the widget automatic on your blog and click-only on your pricing page. The choice applies to every visitor on that domain, including mobile.
Which method should you call?
Method | Use it when |
|---|---|
| You want the widget to appear and the conversation to start. This is the usual choice for a button. |
| You want the widget visible but want the visitor to start the conversation. |
| You want the conversation to start without changing whether the widget is visible. |
| You want to hide the widget and leave the conversation running. |
| You want to end the conversation and hide the widget. |
How do you open the widget from a button?
<button id="talk-to-sales" type="button">Talk to Sales</button>
<script>
document.getElementById("talk-to-sales").addEventListener("click", () => {
if (!window.AISeller?.showAndConnect) {
console.warn("The Docket widget is not ready.");
return;
}
window.AISeller.showAndConnect();
});
</script>The readiness check matters. Calling showAndConnect() before the widget has finished loading can leave the visitor looking at a connection error, so guard the call rather than assuming the script is ready.
How do you pass visitor details at the same time?
Set the context first, check that it succeeded, then connect. If you connect first, the conversation starts without the data.
async function startConversation(visitor) {
if (!window.AISeller?.setContext || !window.AISeller?.showAndConnect) {
console.warn("The Docket widget is not ready.");
return;
}
const result = await window.AISeller.setContext({
name: visitor.name,
company: visitor.company,
source: "pricing-page"
});
if (!result.success) {
console.warn(result.message);
return;
}
window.AISeller.showAndConnect();
}How do you check that it works?
Open the deployed page in a private browser window.
Confirm the widget does not appear on its own.
Select your button.
Confirm the widget appears and the conversation starts.
Repeat on a phone-width layout, where the launcher and any fixed page elements sit closer together.
Frequently asked questions
The Widget Behaviour section is empty. What is missing?
The agent has no whitelisted domains yet. Open Whitelist Domains on the same tab, add the domain where the widget runs, save, and the behavior options appear for it.
Why does the widget still open by itself?
The domain is probably still set to All Pages or Selected Pages. Check the card for that exact domain, since each one is configured separately, and confirm the change was saved.
The widget appears but no conversation starts. What went wrong?
You are most likely calling show(). Use showAndConnect() when you want the conversation to begin as well.
The conversation starts but the widget stays hidden. What went wrong?
That is connect() on its own. Use showAndConnect().
Can I use one setting for desktop and another for mobile?
Not in Docket. Widget behavior is configured per domain, not per device, so both get the same setting. If you need different behavior, detect the device in your own page code and decide there whether to call showAndConnect().
Can I open the widget from a link in another tool, such as an email?
Not directly, because the method has to run on your page. Link to a page that reads its own query string and calls showAndConnect(), or link to the agent's standalone page instead. See Passing Context via URL Parameters to Marketing Agents.