When Context Is Sent to the Agent

Last updated: October 26, 2026

Dynamic context is attached at one specific moment: when Docket creates the conversation. Anything you set before that point travels with the conversation. Anything you set after it waits for the next one.

That single rule explains most of the timing problems people hit, including the classic "it only works the second time".

What happens between setContext() and the conversation?

Stage

What happens

You call setContext()

The widget checks the object, encrypts it, and holds it in the browser as pending context.

The conversation is created

The widget sends the pending payload with the request as dynamic_context.

Docket confirms

The conversation is created and the pending payload is cleared from the browser.

The request fails

The pending payload is kept so the attempt can be retried.

A conversation is already running

Calling setContext() does not change it. The new payload waits for the next conversation.

What is the correct order of calls?

Wait for setContext() to resolve, confirm it succeeded, and only then start the conversation.

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

if (result.success) {
  window.AISeller.showAndConnect();
} else {
  console.warn(result.message);
}

The await matters. setContext() encrypts the payload before storing it, so the work is not finished the instant the function returns.

When should you set context in common situations?

Situation

When to set context

Signed-in visitor

Once their details are available, and before they can open the agent.

Form submission

After the fields validate, and before showAndConnect().

Standalone or iframe page

Put ctx_ parameters in the URL that loads the agent page.

Visitor logs out

Call resetContext() before anyone else can start a conversation.

Single-page app route change

Set the complete new context object for the new journey.

How do you check the timing?

  1. Open your deployed page in a private browser window.

  2. Call setContext() and look at the resolved result.

  3. Confirm success is true before starting the conversation.

  4. Start the conversation and confirm the agent uses the value.

  5. Call setContext() again while that conversation is open, and confirm it does not change it.

  6. Start a new conversation and confirm the newer values are used.

Frequently asked questions

My context only works on the second conversation. Why?

It is being set after the first conversation has already started. Move the call earlier, and make sure you await it before calling showAndConnect().

Can I update context mid-conversation?

No. The conversation keeps the context it was created with. A new call applies to the next conversation.

Does the agent's opening message use my context?

Do not rely on it. Context is reliably available in the conversation itself, but the opening greeting is generated separately and may not reflect the values you passed. Ask a follow-up question if you want to confirm the agent has the data.

What happens to my context if the conversation fails to start?

It stays pending in the browser so the request can be retried. You do not need to set it again.

How long does pending context last?

Until a conversation consumes it, you replace it, or you call resetContext(). It is held in browser storage, so it survives a page reload.

Related articles