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 | 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 |
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 |
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 |
Standalone or iframe page | Put |
Visitor logs out | Call |
Single-page app route change | Set the complete new context object for the new journey. |
How do you check the timing?
Open your deployed page in a private browser window.
Call
setContext()and look at the resolved result.Confirm
successistruebefore starting the conversation.Start the conversation and confirm the agent uses the value.
Call
setContext()again while that conversation is open, and confirm it does not change it.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.