Using the AISeller JavaScript API

Last updated: October 26, 2026

Docket's widget exposes a small JavaScript API on window.AISeller. Use it to tell the agent who the visitor is before a conversation starts, and to open or close the widget from your own buttons. Everything on this page runs in the browser, so you add it to your website code rather than configuring it in Docket.

Two things have to line up before any of it works: the variables you send from JavaScript must match the variables configured on the agent, and you must send them before the conversation begins.

What can the AISeller JavaScript API do?

The API covers two jobs. setContext() and resetContext() manage the visitor data the agent will see. The remaining methods show, hide, connect and disconnect the widget.

Method

What it does

window.AISeller.setContext(data)

Encrypts and stores visitor context for the next conversation. Returns a Promise.

window.AISeller.resetContext()

Replaces pending context with an empty object. Returns a Promise.

window.AISeller.show()

Makes the widget visible without starting a conversation.

window.AISeller.hide()

Hides the widget without ending the conversation.

window.AISeller.toggle(show)

Shows or hides the widget. Omit show to flip the current state.

window.AISeller.connect(options)

Starts the agent connection without changing visibility.

window.AISeller.showAndConnect(options)

Shows the widget and starts the conversation. This is the method most sites want.

window.AISeller.hideAndDisconnect()

Ends the conversation and hides the widget.

What do you need before you start?

  • The Docket widget script installed on your website.

  • The agent deployed to the domain where you will call the API.

  • Every visitor field you plan to send configured on the agent under Dynamic Context Ingestion.

How do you configure the variables the agent will accept?

Docket only uses variables that are configured on the agent. A key you send that has no matching variable is dropped, and nothing appears in the browser console to tell you so. Configure the variables first, then write the JavaScript to match.

  1. Sign in to app.docketai.com and open Marketing Agent Configuration.

  2. Select your agent and stay on the Agent tab.

  3. Open Dynamic Context Ingestion with the chevron, then turn the section on with its switch.

  4. Select Add Variable.

Dynamic Context Ingestion section on the Agent tab with the enable switch and the Add Variable button outlined in red

Each variable has three parts.

  1. In Variable Name, enter the exact key your JavaScript will send, for example company. Docket matches this key character for character, including capitalization.

  2. In Map to Docket Field, choose the visitor or account field where Docket should store the value. This is optional.

  3. In Context for Agent, describe what the field means and how the agent should use it during a conversation.

  4. Select Add Variable to save the variable, then select Save on the agent.

Add Variable panel showing the Variable Name field, the Map to Docket Field picker and the Context for Agent description box, each outlined in red

What does Map to Docket Field change?

Mapping is about storage, not delivery. An unmapped variable still reaches the agent and still shapes the conversation. Mapping it tells Docket to also write the value onto the visitor or account record, so it is available after the conversation ends.

The picker groups the available targets under Visitor and Account. Visitor fields include City, Country, Email, First Name, Last Name, Salutation, Title and Department. Account fields include Name, Industry, Annual Revenue, Employee Count and Location. Use Add New Item in either group to create a custom field.

Map to Docket Field picker open, showing the Visitor field group outlined in red with entries such as visitor.city, visitor.email and visitor.first_name

How do you send visitor context?

Call setContext() with a flat object and wait for the result. Every value must be a string, number, boolean, or null.

const result = await window.AISeller.setContext({
  name: "Jordan",
  email: "jordan@example.com",
  company: "Northstar Labs",
  plan: "Enterprise",
  isCustomer: true
});

if (!result.success) {
  console.warn("Docket context was not stored:", result.message);
}

The Promise resolves to an object you should check rather than assume:

{ success: true, message: "Context stored successfully" }

Each call replaces the whole pending payload. Send the complete object you want the next conversation to receive, not just the fields that changed.

How do you open the widget from your own code?

Set the context first, confirm it succeeded, then connect. showAndConnect() both reveals the widget and starts the conversation.

async function startSalesConversation() {
  if (!window.AISeller?.setContext || !window.AISeller?.showAndConnect) {
    console.warn("The Docket widget is not ready.");
    return;
  }

  const result = await window.AISeller.setContext({
    name: "Jordan",
    company: "Northstar Labs",
    source: "pricing-page"
  });

  if (!result.success) {
    console.warn(result.message);
    return;
  }

  window.AISeller.showAndConnect();
}

Call the API only after the Docket script has finished loading. If your trigger can fire early, guard it as shown above, or wire it to a button that only becomes active once the script is ready. See Triggering the Widget Programmatically for the full pattern, including the agent setting that stops the widget opening on its own.

How do you check that it works?

  1. Open your website in a private browser window.

  2. Confirm window.AISeller exists in the browser console.

  3. Call setContext() with test values and confirm success is true.

  4. Call showAndConnect() and start a conversation.

  5. Ask the agent something that should use one of your variables.

  6. Call resetContext(), start a new conversation, and confirm the earlier values are gone.

Frequently asked questions

Why does the agent ignore one of my fields?

The key almost certainly does not match a configured variable. Docket compares names exactly, so Email does not match email and company does not match company_name. Nothing is logged when a key is dropped. Troubleshooting Dynamic Context Not Reaching the Agent walks through this.

Can I call setContext() during a conversation?

You can, but it will not change the conversation already running. Context is attached at the moment Docket creates the conversation, so a later call applies to the next one. See When Context Is Sent to the Agent.

What happens if I send an array, a Date, or a nested object?

The call resolves with success: false and a message naming the field, for example Context field "tags" must be a simple type (string, number, boolean, or null). Convert the value to a string or number before sending it.

Do I need to reset context after every conversation?

No. Docket clears the pending payload once the backend confirms the conversation was created. Reset when the visitor's identity changes, such as on logout. See When and How to Reset Visitor Context.

Is the visitor data encrypted?

Yes. The widget encrypts the payload in the browser before storing it, using AES-256-GCM for the data and RSA-OAEP with SHA-256 for the key. Encryption does not make every field appropriate to send, so read Security Guidelines for Passing Visitor Context before you choose fields.

Can I pass context without writing JavaScript?

Yes, on a standalone or embedded agent page. Add ctx_ query parameters to that page's URL. See Passing Context via URL Parameters to Marketing Agents.

Related articles