Context

Context is a free-form key/value object you attach to the chat widget. It travels with every message the user sends and tells the AI where the user is in your app and what’s relevant right now.

Why Send Context

Without context, the AI only sees the user’s message. With context, it can:

• Answer relative questions accurately — “What’s in my cart?”, “Why was I charged?”, “Show similar items” — all need the AI to know cart state, current screen, viewed item, etc.
• Match the right tool — tools can require context keys to be eligible (e.g. a “Cancel reservation” tool only fires if reservationId is in context)
• Personalize tone & depth — userRole: 'premium' or language: 'tr' shape responses without you writing branching logic

The AI receives context as part of the system message; it doesn’t see it as user-typed text.

How to Send It

Pass context and an optional contextDescription to the widget:

<Qafka
  context={{
    currentScreen: 'ProductDetail',
    productId: '123',
    userRole: 'premium',
    cart: { itemCount: 3 },
  }}
  contextDescription="User is viewing a product detail page"
/>

Context is sent with every message in the session — you don’t need to repeat it per send.

Privacy & Storage

Context is persisted alongside the conversation in the Qafka backend (it’s a JSON column on the Conversation row). That means:

• Anything you put in context is stored as long as the conversation is stored and is visible in the dashboard’s conversation viewer.
• It can be retrieved later for analytics, debugging, and conversation replay.

Don’t put in context:

• ❌ Passwords, session tokens, OAuth tokens, API keys
• ❌ Full credit card numbers, CVVs, bank account numbers
• ❌ National ID numbers, passport numbers, SSNs
• ❌ Plain-text personal data you wouldn’t want in your analytics database (full home address, medical conditions, etc.)
• ❌ Any data your privacy policy or compliance regime (KVKK, GDPR, PCI-DSS) doesn’t permit you to log

Safe to put in context:

• ✅ Internal IDs (userId, productId, orderId, subProjectId) — useful for tool calls, low risk
• ✅ Non-PII flags and roles (userRole: 'premium', isFirstSession: true)
• ✅ App state (currentScreen, cart.itemCount, selectedFilter)
• ✅ Locale, theme preference, feature flags

Best Practices

• Keep keys stable across messages. Use the same key names (currentScreen, not screen once and currentScreen later) — the AI learns to depend on them.
• Update context when state changes, not on every render. The widget only re-sends what’s in context at message-send time.
• Use contextDescription for non-obvious keys — subProjectId: "downtown-mall" means nothing to the AI; “user is browsing the Downtown Mall location” does.
• Prefer flat structure for tool matching. Tools usually filter on top-level keys — { shoppingMallId: 'x' } is easier than { user: { mall: { id: 'x' } } }.
• Pass IDs, resolve server-side. Send productId: '123', not the full product object — Qafka can fetch the product details if a tool needs them.