> ## Documentation Index > Fetch the complete documentation index at: https://docs.callers.ai/llms.txt > Use this file to discover all available pages before exploring further. # Page Guide > Let your web call agent see the page the visitor is on and highlight, scroll to or open elements while it talks, with form values and private areas never shared. Page Guide lets the agent see a text summary of the page your widget is on, and point at it while it speaks. When a visitor asks "where do I change my plan?", the agent answers from what is actually on screen: the page scrolls to the right button and a soft ring marks it as the agent says "click **Upgrade to Pro**". If you allow it, the agent can also open a link on your site. Use it for product tours, support on complex pages, and any flow where "it's the third button on the left" isn't good enough. > [!NOTE] > > Page Guide is in early access. Behavior and limits may change, and Callers may ask for feedback on how your agent uses it. ```html theme={"dark"} ``` ![A pricing page with the Upgrade to Pro button marked by a soft Page Guide ring and the Callers call window open on the right](https://mintcdn.com/voxiaai/dmHXPB02yobC5Lfr/images/documentation/sdk/page-guide-spotlight.png?fit=max\&auto=format\&n=dmHXPB02yobC5Lfr\&q=85\&s=cd44fc2d43c173f4a597bfd8c7a13951) While the agent says “click Upgrade to Pro”, a thin ring and a soft glow mark the button, and the rest of the page is shaded very lightly. The call window stays open beside it. > **[Try it with your agent](https://sdk-playground.callers.dev/?pageGuide=true)** > > Opens the playground with Page Guide on. Start a test call and ask about the sample site. > **[Watch the demo without a call](https://sdk-playground.callers.dev/page-guide)** > > A simulated reply plays highlight and scroll actions against a sample billing page. No credentials, no audio. ## What the agent can do | Action | What the visitor sees | Allowed by default | | - | - | - | | Read | Nothing. The agent receives a text summary of the page. | Yes | | `highlight` | The element is scrolled into view and marked in the [highlight style](#highlight-styles) you choose, by default a thin ring with a light shade over the rest of the page | Yes | | `scroll` | The page scrolls the element to the center of the view | Yes | | `navigate` | The browser opens a link that is on the page and stays on your site. Only real links, never buttons or downloads | No, list it in `actions` | | `clear` | Any highlight is removed | Always | The agent never clicks, types or submits anything. The visitor always does that themselves. Actions are timed to the agent's words and stop when the visitor starts speaking. The agent can only point at elements it was shown in a summary, and can only open links that appear in one. It never highlights an element the visitor can't see: an element that is hidden, or covered by something floating over the page, is reported instead of drawn. You don't change the agent's script for this. Turning Page Guide on in the SDK gives the agent the ability for that call, and it learns the page format from the summary itself. ## How it works

` and image-map `` elements) can be opened. Buttons, links with a `download` attribute, `javascript:` links, bare `#` anchors and other sites are refused with the outcome `not-allowed`, so opening something never submits a form or starts a download. When `navigate` isn't allowed but `highlight` is, a request to open a link highlights the link instead, so the visitor still sees where to go. On a multi-page site, the browser loads the new page, **which ends the call**: the SDK is reloaded with the page. On a single-page app, pass `onNavigate` and route in place so the call survives (see the [React example](#react-with-react-router)). Keep `navigate` off on multi-page sites unless a dropped call is acceptable. ### The visitor notice While Page Guide is on, the call window shows a one-line notice before and during the call: **The agent can see this page** by default, with a tooltip explaining that what the visitor types in forms is never shared. During the call the line has a **Stop** button. Stopping cancels pending actions, removes any highlight, stops sending summaries and tells the agent it can no longer see the page; the line then reads **Page sharing is off** with a **Share** button to turn it back on. Change the text with `notice`. Keep it honest and short; the tooltip is fixed. ![Call window header showing the text The agent can see this page with a Stop link](https://mintcdn.com/voxiaai/UGuY0UNIphM-6pUX/images/documentation/sdk/page-guide-notice.png?fit=max\&auto=format\&n=UGuY0UNIphM-6pUX\&q=85\&s=22381d3ebc5db44662aee07e9257c1a4) The notice under the call controls tells the visitor the agent can see the page. Stop turns page sharing off for the rest of the call. ## Turn it on ```html Script tag theme={"dark"} ``` ```javascript Programmatic theme={"dark"} import { WebCall } from '@callers/web-sdk'; const webCall = new WebCall({ token, pageGuide: { actions: ['highlight', 'scroll', 'navigate'], hideSelectors: ['.account-menu', '#billing'], highlight: 'soft', color: '#0f766e', maxElements: 200, notice: 'Our assistant can see this page to help you', onNavigate: (path) => router.push(path), // single-page apps onPageAction: (action, outcome) => console.log(action.type, action.ref, outcome), }, }); ``` `pageGuide: true` (or `data-page-guide="true"` alone) uses the defaults: highlight and scroll, 150 elements, the standard notice and privacy rules. The script tag can set `actions`, `hideSelectors` and the highlight options (`highlight`, `dim`, `color`, `label`); the other options need the programmatic form. ## Configuration reference **pageGuide** `boolean | PageGuideConfig` (default: false) `true` turns Page Guide on with the defaults. An object sets the options below. Script tag: `data-page-guide="true"`. ### `PageGuideConfig` **actions** `PageActionType[]` (default: \['highlight', 'scroll']) What the agent may do: any of `highlight`, `scroll` and `navigate`. `clear` is always allowed. Script tag: `data-page-guide-actions`, comma-separated; unknown names are dropped. **hideSelectors** `string[]` CSS selectors for areas never shared with the agent, including everything inside them. `[data-callers-private]` is always hidden. An invalid selector is ignored rather than breaking the capture. Script tag: `data-page-guide-hide`, comma-separated. **highlight** `HighlightStyle` (default: 'soft') How the element the agent points at is shown: `soft`, `glow`, `outline`, `spotlight` or `none`. See [Highlight styles](#highlight-styles). Script tag: `data-page-guide-highlight`; unknown values fall back to `soft`. **dim** `number` How dark the shade over the rest of the page is, from `0` (none) to `0.5`. Values outside the range are clamped. Applies to `soft` (default `0.1`) and `spotlight` (default `0.28`); the other styles have no shade. Script tag: `data-page-guide-dim`. **color** `string` The ring and glow color, any CSS color. Defaults to the widget theme's primary color. Script tag: `data-page-guide-color`. **label** `boolean` (default: true) `false` never shows the name label next to the element. Even when `true`, the label appears only when the element doesn't already show its name. Script tag: `data-page-guide-label="false"`. **maxElements** `number` (default: 150) How many elements a summary lists, 1–300. Values outside the range are clamped. Larger pages keep what is in view and interactive first. **notice** `string` (default: The agent can see this page) The line shown in the call window telling visitors the agent can see the page. **onNavigate** `(path: string) =\> void` For single-page apps. Receives the path (with query string and hash) of the link the agent wants to open; route to it in place. Without it, the browser loads the new page, which ends the call. **onPageAction** `(action: PageAction, outcome: PageActionOutcome) =\> void` Called for every action the agent takes, with its outcome. Use it for analytics or to react in your own UI. ### Types ```typescript theme={"dark"} import type { PageGuideConfig, PageAction, PageActionType, PageActionOutcome, HighlightStyle } from '@callers/web-sdk'; type PageActionType = 'highlight' | 'scroll' | 'navigate' | 'clear'; type HighlightStyle = 'soft' | 'glow' | 'outline' | 'spotlight' | 'none'; interface PageAction { type: PageActionType; ref?: string; // the element's ref in the summary, e.g. 'e19'; absent for clear charOffset: number; // where in the sentence the action belongs } type PageActionOutcome = | 'done' // the action ran | 'not-allowed' // the action isn't in `actions`, the link leaves your site, or it isn't a real link | 'not-found' // the element is no longer on the page | 'hidden' // on the page but not visible, e.g. a carousel slide that isn't showing | 'covered'; // under something floating over the page wherever it scrolls ``` ## Runtime API ### `webCall.getPageContext()` Returns the exact summary the agent would receive right now, as text, or `null` when Page Guide is off. Call it on any page to audit what is shared, write tests for your `hideSelectors`, or debug why the agent can't find a button. ```javascript theme={"dark"} console.log(window.Callers.widget.getPageContext()); // With a programmatic WebCall: console.log(webCall.getPageContext()); ``` ### Transcript messages Transcript messages from `onTranscriptChanged` and `onTranscriptMessage` carry the agent's sentences with their actions, after the tags were stripped from the text: ```javascript theme={"dark"} new WebCall({ token, pageGuide: true, onTranscriptChanged: (messages) => { const latest = messages.filter((m) => m.role === 'assistant').at(-1); latest?.llmResponseSentences?.forEach((sentence) => { console.log(sentence.textWithoutEmotions, sentence.pageActions); // "click Upgrade to Pro." [{ type: 'highlight', ref: 'e19', charOffset: 0 }] }); }, }); ``` The summaries themselves are not streamed back in the transcript. ## Privacy and security Every rule below is enforced in the visitor's browser, before anything leaves it. The summary is plain text you can read with `getPageContext()`. ### What never leaves the browser * **Form values.** Fields are described by their label and state (`filled`, `empty`, `checked`), never by what is in them. The capture never reads a field's value into the summary. * **Sensitive fields** are additionally marked `private field`: password and hidden inputs, fields with `autocomplete` of `cc-*`, `one-time-code`, `new-password` or `current-password`, and fields whose name, id, `aria-label` or placeholder mentions a password, card, CVV/CVC, SSN, IBAN, account or routing number, secret, token or PIN. * **Emails and long numbers** in page text, headings, titles and element names are replaced with `(email hidden)` and `(number hidden)` before anything is cut short, so a truncated email can't slip through. Dates and prices have too few digits to match. * **Private areas.** Anything inside `[data-callers-private]` or your `hideSelectors` is never walked. If an element's own name would be read from text that contains a private area, that element is left out too, while its other children are still listed. * **Hidden content**, the widget, the spotlight overlay, query strings and hashes in the URL, and the addresses of external links. Mark private areas in your HTML: ```html theme={"dark"}

Saved payment methods

…

``` ### What the agent can't do * It can only point at elements that appeared in a summary this widget sent, so it can't reach into hidden areas even by guessing a ref. * It can't click, type, submit, or open a URL it made up. `navigate` reaches only a same-site link from the summary, and only when you allow navigation. * Page text reaches the agent as untrusted content. Instructions written on the page can't give the agent new abilities: the worst an injected instruction can do is highlight an element or open a same-site link, if you allowed it. ### Server side Summaries are accepted only for calls that opted in (the SDK marks the call when Page Guide is on), so a page can't push context into a call that didn't ask for it. The agent reads the latest summary on turns about the page; summaries are not streamed back to the browser in the transcript. > [!NOTE] > > Page text is sent to Callers and processed by the language model behind your agent, like the rest of the conversation. Mark anything personal with `data-callers-private`, even sections with no form fields, and review `getPageContext()` on pages that show account data. ## Single-page apps In a SPA, in-app navigation changes the DOM without a page load. The SDK watches DOM changes, `popstate` and `hashchange`, so a new route produces a new summary without any extra code. Two things need your attention: 1. **`onNavigate`.** If you allow `navigate`, route in place so the call survives. Without it, `location.assign` loads the page and the call ends. 2. **Stable `WebCall`.** Create the `WebCall` once, outside the component tree that re-renders on route changes, so the call and the page refs survive navigation. ### React with react-router ```jsx theme={"dark"} import { useEffect, useRef } from 'react'; import { useNavigate } from 'react-router-dom'; import { WebCall } from '@callers/web-sdk'; export function CallersWidget({ token }) { const navigate = useNavigate(); const navigateRef = useRef(navigate); navigateRef.current = navigate; // always the latest navigate, without recreating the WebCall useEffect(() => { const webCall = new WebCall({ token, pageGuide: { actions: ['highlight', 'scroll', 'navigate'], hideSelectors: ['[data-account]'], onNavigate: (path) => navigateRef.current(path), // '/billing?tab=invoices#history' onPageAction: (action, outcome) => { if (outcome !== 'done') console.warn('page action', action.type, action.ref, outcome); }, }, }); return () => webCall.destroy(); }, [token]); return null; } ``` Mount `CallersWidget` once at the app root, inside the router so `useNavigate` works. For Next.js, Vue Router or Angular, pass the equivalent of `router.push(path)` to `onNavigate`. ## Tips for pages that guide well * Give buttons and links clear, visible text or `aria-label`s. The agent can only point at what it can name, and the spotlight label shows that name to the visitor. * Use real `