Pass context to the widget

Send page, session, and user context to your agent so it can give personalized, situation-aware responses.

Give your agent context about who the user is so it can respond more specifically, like their name, plan, current page, or where they are in a flow.

How context reaches your agent

Context that the agent (the model) should actually read is passed as HTTP headers via the widget's aiChatSettings.headers prop. You define a headers schema on the agent, and the values become available in two places:

In the prompt, via the {{headers.<key>}} template syntax
In context fetchers, which can call your own APIs using header values and expose the result as {{<variable>.<field>}}

Automatic context (timestamp & timezone)

The chat components automatically send the following headers with each request to provide client context:

Header	Description	Example Value
`x-inkeep-client-timestamp`	The client's current timestamp in ISO 8601 format	`2025-01-30T18:15:00.000Z`
`x-inkeep-client-timezone`	The client's timezone identifier	`America/New_York`

These headers enable your agents to provide time-aware responses. See Headers to learn how to use these values in your agent configuration.

Page & session context (custom headers)

You can pass custom headers to the chat components via the headers prop in aiChatSettings. Common use cases include passing the current page URL, user context, or session metadata. Custom headers are validated against a schema you define in the agent settings, then made available in your agent prompt via template syntax.

In the following example, you'll pass the current page URL to the agent.

Define the headers schema

In the Visual Builder, navigate to Agents in the left sidebar, select your agent, then open the Agent Settings pane and scroll down to Headers schema and add the following schema:

{
  "type": "object",
  "properties": {
    "x-current-url": {
      "type": "string",
      "description": "The URL the user is currently viewing."
    }
  },
  "required": []
}

Reference the header in your agent prompt

Use the key defined in your headers schema with the {{headers.<key>}} template syntax:

The user is currently viewing {{headers.x-current-url}}.

Pass the header value from your chat component

Note

Update header values whenever the context changes — on client-side navigation, after login, or when the user advances a step. In React, derive them from state/router so a re-render passes new values; with the JavaScript API, call .update({ aiChatSettings: { headers: { ... } } }) (as shown above).

User context (name, plan, onboarding step)

User attributes work exactly like the page example above — declare each key in your headers schema, reference it in the prompt, and pass it from the widget. The values come from your app's auth or session state rather than the browser. This example passes the user's name and plan; add more keys (like x-onboarding-step) the same way.

Define the headers schema

In the Agent Settings → Headers schema, add a property for each attribute you want to pass:

{
  "type": "object",
  "properties": {
    "x-user-name": {
      "type": "string",
      "description": "The user's display name."
    },
    "x-user-plan": {
      "type": "string",
      "description": "The user's subscription plan, e.g. free or pro."
    }
  },
  "required": []
}

Reference the headers in your agent prompt

Use the keys from your headers schema with the {{headers.<key>}} template syntax:

You are helping {{headers.x-user-name}} on the {{headers.x-user-plan}} plan.

Pass the header values from your chat component

For richer data, use a context fetcher: pass an identifier like x-user-id as a header, and have the agent fetch the full user record from your API at conversation start. The fetched fields are then available in the prompt as context variables.

On this page