Skip to main content
Verified Context Injection is the way a customer’s backend passes trustworthy, cryptographically verified user context into a PolyAI conversation. The customer’s backend creates a short-lived signed token (a JWT, or JSON Web Token) using a signing key they generated in Agent Studio. Our platform verifies the signature, stores the verified values against the conversation, and makes them available to the agent’s functions as read-only at every turn. Internally we call the service that does this Context Vault. The mental model to give the customer: a per-conversation lockbox. Only the customer’s backend (which holds the signing key) can put values into it. The agent’s functions can only read them out. Nothing in the browser, the widget, or any other layer can forge or tamper with the values.

​
The problem it solves

A primitive implementation of context injection would allow customers to pass casual context into the widget for the agent to use, but with that approach the widget can’t vouch for it — anyone can edit a value in the browser. That means it can’t be relied on for anything that matters. Context Vault closes that gap. The customer’s backend signs the context; PolyAI verifies the signature server-side before the agent sees anything. That makes a value like account_tier: "premium" trustworthy enough to gate entitlements on.

​
What it does

  • Sets context from a trusted origin: The customer’s backend signs a JWT with a key they generated in Agent Studio. The token has a 30-second lifetime and carries up to 8KB of context data (fields such as customer identifier, account tier, or a short-lived auth token). The widget carries the opaque token but never sees the signing key.
  • Verifies the signature and stores verified values: Our platform validates the signature, checks the token binding and expiry, then stores the verified context payload against the conversation. Nothing bypasses this validation path.
  • Reads into functions as read-only fields: Every turn, the function runtime receives a read-only object (accessed as conv.context_vault) with the verified fields. Functions can act on them, for example calling the customer’s application programming interface (API) with the customer identifier, checking the account tier, or using a short-lived auth token to call a downstream service. Values are never surfaced in prompts or transcripts unless the function explicitly copies them into state.

​
Benefits:

  • Trust: Customers knows the identity and entitlement values came from their own systems, not from a manipulated browser session. That is the difference between an assistant that can act on account data and one that cannot.
  • Personalised from the first turn: The agent skips identity verification questions when the user is already authenticated on the customer’s side. Cuts turns, cuts abandonment.
  • Compliance-friendly: Verified context lives only as long as the conversation, is never surfaced in prompts by default, and is scoped strictly to a single session. The security posture holds up in procurement conversations.

​
How it works

  • A conversation starts. PolyAI mints a unique context_id for that specific conversation and hands it to the widget. Just before the agent joins, the widget calls the customer’s onContextRequired callback with it.
  • The customer’s backend signs a token. A short-lived JWT whose subject is exactly that context_id, carrying the context payload. Signing always happens on their server — never in the browser.
  • PolyAI verifies and attaches it. The vault checks the signature and that the token was minted for this conversation, then stores the context. The agent reads it on turn 1.
Because verification is server-side and bound to a PolyAI-issued context_id, a token can’t be replayed against a different conversation, and a forged token is rejected. Two usage patterns, one integration. The same callback powers both:
  • At conversation start (default, recommended) — verified context is present before the agent joins.
  • Mid-conversation refresh — if the user’s context changes while chatting, the customer’s page calls refreshVerifiedContext(). Same callback, fresh token, last write wins, no interruption to the live conversation.

​
Example use cases

  • Entitlement gating. An account_tier of premium is signed by the customer’s backend, so the agent can act on it with confidence rather than taking the browser’s word for it.
  • Identified-from-turn-1 conversations. A customer_id is attached before the agent joins, so there’s no “can I take your account number?” opening.
  • Passing a short-lived auth token. The customer’s backend mints and signs it; the agent receives it as trusted, read-only context.
  • User logs in partway through a chat. The customer’s page calls refreshVerifiedContext() from their login success handler. The same callback re-runs, a fresh token replaces the old context, and the conversation carries on uninterrupted.

​
What the customer has to build

  • A signing key provisioned for their project — a key ID and a secret, from Agent Studio or their PolyAI rep. The key ID is stable across rotation.
  • A backend endpoint that signs a JWT with that secret.
  • A small amount of JavaScript on their page to register the onContextRequired callback inside onReady.
They never fetch, store, or submit the context_id or the token — the widget owns all of that. They only sign and return.

​
Facts you can quote

​
It always fails open

The conversation always starts. Verified context is best-effort and never blocks the user.

​
Constraints and caveats

  • Signed, not encrypted. The token proves origin, not secrecy — values travel in plaintext inside it. Hyper-sensitive data isn’t a fit today; a server-to-server path is planned. Route those conversations back to us.
  • Web chat only. Context Vault today covers the web chat widget via the browser SDK. Server-to-server and voice transports are future work.
  • V2 widget only. V1 is deprecated.
  • The agent must degrade gracefully. Because context can legitimately be absent, agents should fall back sensibly — for example asking the user to identify themselves — rather than assuming verified context is always there. Worth raising in any design conversation.

​
Good to know

  • Signing key provisioning is separate work. Today the guidance is “get a key from Agent Studio or your PolyAI rep” — the Agent Studio surface for this is not yet built out.
  • One integration point, two behaviours. Customers only ever implement onContextRequired. The mid-conversation refresh reuses it rather than needing anything new wired up.
  • The vault set is idempotent. A refresh fully replaces the previous context — last write wins.

Enable Verified Context Injection

Step-by-step integration: register the callback, sign the token, handle refresh and timeouts.
Last modified on August 21, 2026