Custom Context

Custom context is the bridge between your website state and the AI. Whatever you pass via context() becomes available to the agent during the conversation, so it can reference specific cart items, the current listing, or the user's plan.

Use cases

E-Commerce / Shopify — pass current cart so the AI can answer "Will my order arrive before Friday?"
SaaS — pass user's plan, trial days left, account ID so the AI tailors advice
Real Estate — pass the listing the user is viewing so the AI can answer property-specific questions
Marketplace — pass the seller / product context

Vanilla JS

// Shopify / E-Commerce
widget.context({
  cart: {
    items: [
      { name: "Nike Air Max 90", size: "42", price: 149.99 },
      { name: "Adidas Hoodie", qty: 2, price: 59.99 },
    ],
    total: 269.97,
    currency: "EUR",
  },
});
 
// SaaS
widget.context({
  plan: "trial",
  trialDaysLeft: 3,
  accountId: "acc_12345",
});
 
// Real Estate
widget.context({
  property: {
    address: "Musterstr. 12, Berlin",
    price: 450000,
    rooms: 3,
  },
});
 
// Subsequent calls merge — they don't replace
widget.context({ promoCode: "SUMMER20" });
// → context now has cart + plan + property + promoCode

To clear everything:

widget.resetContext();

React / Next.js & script-tag (via event)

Same event pattern as identify:

window.dispatchEvent(
  new CustomEvent("bitpalm-context", {
    detail: {
      slug: "your-agent-slug",
      cart: { items: [...], total: 99.99 },
    },
  })
);

How the AI uses it

Whatever you pass shows up in the AI's context window during the conversation. The agent will reference it when relevant — e.g.:

User asks "How long does shipping take?" → AI sees the cart's currency: EUR and country, answers with EU shipping times.
User asks "What's included in my plan?" → AI sees plan: trial and answers with trial features.
User asks "Is this property close to schools?" → AI sees the address and looks it up.

The agent knows when to use context — you don't need to instruct it explicitly.

Limits and best practices

Size limit: 4 KB. Exceeding the limit logs a console warning and the context is dropped. Strip noisy fields (full Shopify product objects → just name + price + qty).
Session-only. Context is not persisted in the database. It exists for the duration of the visitor's tab.
No sensitive data. Don't pass passwords, full credit card numbers, or anything regulated. Use identify() with a signed payload for trust-sensitive data.
Update on relevant changes. Re-call context() whenever the cart updates, the user changes plan, or they navigate to a different listing.

Pattern: keeping context in sync

If you have a Zustand / Redux / Pinia store, update the widget on store changes:

// React + Zustand
useEffect(() => {
  return useStore.subscribe(
    (state) => state.cart,
    (cart) => {
      window.dispatchEvent(
        new CustomEvent("bitpalm-context", {
          detail: { slug: "your-slug", cart },
        })
      );
    }
  );
}, []);