> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zephlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Page context

> Send page context to the agent so it can give contextual, relevant answers

## Overview

By default the agent only sees what the visitor types. With **page context**, you can tell the agent *where* the visitor is and *what* they're looking at — a pricing page, a product detail, an account settings screen — so it can give smarter, more relevant answers without the visitor having to explain.

***

## Quick start

<CodeGroup>
  ```html Script tag + inline SDK theme={null}
  <script src="https://unpkg.com/zephlo/dist/zephlo.js"></script>
  <script>
    const zephlo = Zephlo.initialize({
      key: "flk_your_api_key",
      chatbotId: "YOUR_AGENT_ID",
    });

    // Send custom context about the current page
    zephlo.sendContextUpdate({ product: "Pro Plan", price: "$49/mo" });
  </script>
  ```

  ```typescript NPM SDK theme={null}
  import Zephlo from "zephlo";

  const zephlo = Zephlo.initialize({
    key: "flk_your_api_key",
    chatbotId: "YOUR_AGENT_ID",
  });

  zephlo.sendContextUpdate({ product: "Pro Plan", price: "$49/mo" });
  ```
</CodeGroup>

***

## API

### `sendContextUpdate(data, includePageDetails?)`

Sends a context payload to the agent over the active WebSocket connection. Call it whenever the visitor navigates or when relevant page data changes.

<Note>
  Context is delivered on the live chat connection. A brand-new visitor has no connection until they send their first message, so the latest context you set is what the agent sees once the conversation starts. To attach context to a [proactive trigger](/widget/triggers) before any chat begins, use the trigger's `pageContext` option.
</Note>

| Parameter            | Type                  | Required | Description                                                                  |
| -------------------- | --------------------- | -------- | ---------------------------------------------------------------------------- |
| `data`               | `Record<string, any>` | Yes      | Key-value pairs describing the current page context                          |
| `includePageDetails` | `boolean`             | No       | When `true`, automatically appends the page URL, title, and meta description |

```typescript theme={null}
// Custom data only
zephlo.sendContextUpdate({
  product: "Pro Plan",
  price: "$49/mo",
  category: "pricing",
});

// Custom data + automatic page details
zephlo.sendContextUpdate(
  { product: "Pro Plan", price: "$49/mo" },
  true
);

// Page details only (no custom data)
zephlo.sendContextUpdate({}, true);
```

### Auto page details

When `includePageDetails` is `true`, the SDK automatically collects:

| Field              | Source                              |
| ------------------ | ----------------------------------- |
| `url`              | `window.location.href`              |
| `title`            | `document.title`                    |
| `meta_description` | `<meta name="description">` content |

These are merged with your custom `data`. If you pass a key that overlaps (e.g. `title`), your value takes precedence.

***

## What the agent sees

The page context is injected into the agent's prompt as additional context:

```
<additional context>
page_context: {"url": "https://example.com/pricing", "title": "Pricing — Acme", "product": "Pro Plan", "price": "$49/mo"}
</additional context>
```

The agent can use this to tailor its responses. For example, if a visitor asks "What's included?" while on the Pro Plan pricing page, the agent already knows which plan they're looking at.

***

## Updating context

You can call `sendContextUpdate` multiple times. Each call **replaces** the previous context on the server — it does not merge. Send the full context you want the agent to have each time.

```typescript theme={null}
// Visitor navigates to a new page
zephlo.sendContextUpdate({
  page: "checkout",
  cart_total: "$98.00",
  items: 2,
}, true);
```

<Tip>
  For single-page apps, call `sendContextUpdate` on route changes to keep the agent informed as the visitor navigates.
</Tip>

***

## Examples

### E-commerce product page

```typescript theme={null}
zephlo.sendContextUpdate({
  page_type: "product",
  product_name: "Wireless Headphones",
  product_price: "$79.99",
  in_stock: true,
  category: "Electronics",
}, true);
```

### SaaS pricing page

```typescript theme={null}
zephlo.sendContextUpdate({
  page_type: "pricing",
  highlighted_plan: "Pro",
  billing_cycle: "annual",
  currency: "USD",
}, true);
```

### Account dashboard

```typescript theme={null}
zephlo.sendContextUpdate({
  page_type: "dashboard",
  plan: "Enterprise",
  usage_percent: 73,
  days_until_renewal: 14,
});
```

### SPA route change listener

```typescript theme={null}
// React example
useEffect(() => {
  zephlo.sendContextUpdate({
    route: location.pathname,
    page_title: document.title,
  }, true);
}, [location.pathname]);
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Register tools" icon="wrench" href="/widget/tools">
    Give your agent the ability to take actions on your website.
  </Card>

  <Card title="Form tools" icon="rectangle-list" href="/widget/forms">
    Turn any HTML form into an agent-callable tool with zero JavaScript.
  </Card>
</CardGroup>