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

# Widget Context

> Personalize chat widget prompts with page and custom context placeholders

## Overview

Widget context lets one Chatbot adapt to the page or location where it is embedded. The widget sends context values with each chat request, and your agent uses them only when you reference them in the system prompt with placeholders such as `{{ page_path }}` or `{{ location }}`.

Use widget context when the same agent is embedded across multiple pages, branches, departments, or customer locations and needs to answer with the right local details.

<Note>
  Context values are data, not instructions. They do not change your agent unless your saved prompt contains a matching placeholder.
</Note>

## Where to Configure It

<Steps>
  <Step title="Add placeholders in the Playground">
    Open your agent in the dashboard, go to **Playground**, and edit **Instructions (System prompt)**. Add placeholders with double curly braces, for example `{{ location }}`.
  </Step>

  <Step title="Pass context in the embed code">
    Go to **Deploy → Chat Widget**, copy the embed code, and add a `context` object to `humanizing.init`.
  </Step>

  <Step title="Test on the embedded page">
    Visit the page where the widget is installed, start a conversation, and confirm the agent responds with the page or custom value.
  </Step>
</Steps>

## Built-In Page Context

The embed script automatically sends these values from the current page. For example, if a visitor opens `https://example.com/products/widget?utm_source=newsletter#details`, the widget sends:

| Placeholder         | Example                               | Description                                   |
| ------------------- | ------------------------------------- | --------------------------------------------- |
| `{{ page_url }}`    | `https://example.com/products/widget` | Current page URL without query string or hash |
| `{{ page_origin }}` | `https://example.com`                 | Site origin, including protocol and domain    |
| `{{ page_path }}`   | `/products/widget`                    | Current path on the site                      |

For single-page applications, the widget refreshes this page context when the browser URL changes.

### Prompt Example

Add this in **Playground → Instructions (System prompt)**:

```text theme={null}
The visitor is currently on {{ page_path }}.
If their question is page-specific, use that page as the first clue for what they need.
```

Then embed the widget with the standard snippet:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>humanizing.init("YOUR_PUBLIC_KEY");</script>
```

## Custom Context

You can also pass your own context values as the second argument to `humanizing.init`.

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch",
      department: "Service",
      premiumCustomer: true
    }
  });
</script>
```

Then reference those values in the system prompt:

```text theme={null}
You are answering for the {{ location }} location.
If a visitor asks about appointments, route them to the {{ department }} team.
```

At request time, the agent receives:

```text theme={null}
You are answering for the North Branch location.
If a visitor asks about appointments, route them to the Service team.
```

<Tip>
  Use custom context for values that are known by your website, such as branch, market, product line, campaign, customer segment, or language variant.
</Tip>

## Rules and Limits

| Rule                 | Details                                                                |
| -------------------- | ---------------------------------------------------------------------- |
| Placeholder format   | Use `{{ key }}` in the system prompt                                   |
| Key format           | Start with a letter, then use letters, numbers, or underscores         |
| Values               | Strings, numbers, and booleans are supported                           |
| Maximum keys         | Up to 50 context keys are accepted                                     |
| Maximum value length | Values are limited to 500 characters                                   |
| Missing values       | If a key is not provided, the placeholder stays visible as `{{ key }}` |

<Warning>
  Do not put instructions, secrets, access tokens, or private customer data in widget context. The embed code runs in the visitor's browser and should only contain data that is safe to expose on that page.
</Warning>

## Common Patterns

### Multi-Location Agent

Use the same agent for multiple branches:

```html theme={null}
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch",
      phone: "+49 241 000000"
    }
  });
</script>
```

```text theme={null}
You are answering for our {{ location }} branch.
When visitors ask how to reach us by phone, give them {{ phone }}.
```

### Page-Aware Support

Let the agent know which page the visitor is viewing:

```text theme={null}
The visitor is chatting from {{ page_url }}.
Use the current page as context, but answer only from the knowledge base.
```

### Different Departments

Reuse one agent across different department pages:

```html theme={null}
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      department: "Sales"
    }
  });
</script>
```

```text theme={null}
You are currently supporting the {{ department }} department.
If the question belongs to another department, explain who can help.
```

## Troubleshooting

<AccordionGroup>
  <Accordion icon="brackets-curly" title="The placeholder appears in the answer">
    Check that the key in your prompt exactly matches the key in your context object. For example, `{{ location }}` only resolves when the embed sends `context: { location: "North Branch" }`.
  </Accordion>

  <Accordion icon="code" title="My custom value is ignored">
    Make sure the value is a string, number, or boolean. Objects, arrays, null values, and keys that start with an underscore are ignored.
  </Accordion>

  <Accordion icon="route" title="The page path is outdated">
    In most single-page applications, the widget refreshes page context after route changes. If your framework changes content without changing the browser URL, pass a custom context value when initializing or updating the widget.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Edit Prompts" icon="flask" href="/agents/playground">
    Add placeholders to your agent instructions.
  </Card>

  <Card title="Embed the Widget" icon="code" href="/chat-widget/embedding">
    Add context to your widget snippet.
  </Card>
</CardGroup>