Page Guide

<script src="https://cdn.callers.ai/sdk.js" data-agent="YOUR_AGENT_ID" data-page-guide="true"></script>

​

What the agent can do

​

How it works

​

What the summary contains

url: https://app.northwind.example/billing
title: Plans and billing
viewport: 1440x900
e8 heading "Plans and billing" (in view, level 1)
e15 region "Pro plan" (in view)
e19 button "Upgrade to Pro" (in view)
e14 button "Current plan" (in view, disabled)
e27 textbox "Card number" (private field, filled)
e24 link "Talk to sales" (in view) -> /billing#contact-sales
e6 link "Integrations" (in view, external)
e33 text "Dashboards | 3 | 3"
e37 button "Download invoices"
(12 more elements not listed)

• Anything hidden, inert, aria-hidden="true", display: none or visibility: hidden.
• The insides of interactive elements (a button is one line, whatever it contains).
• Closed shadow roots (open ones are walked), the contents of iframes, canvas, video and images without alt.
• The widget itself and the spotlight overlay.
• Everything excluded by the privacy rules below.

​

Limits and ordering

​

When summaries are sent

• A summary is sent when the call connects, and again after the page changes (content updates, scrolling, resizing, in-app navigation, hash changes) and has been quiet for about 1.2 seconds. A page that never settles, such as one with a ticker, is still reported 5 seconds after its first unsent change.
• Sends are at least 3 seconds apart, and an unchanged summary isn’t resent. Scrolling alone changes which elements are “in view”, so only a scroll that changes what the visitor sees produces a new summary.
• A failed send is retried up to 3 times. Failures are reported to onError.
• Sends cost the agent nothing: the summary reaches the agent only on turns where the visitor asks about the page, and only the latest one. Ordinary conversation isn’t slowed down or made longer.

​

How the agent points

• A sentence starts playing about 250 ms after it arrives, or when the previous sentence ends, whichever is later.
• Within a sentence, the action fires at the character timings of the agent’s voice when the provider returns them (within about one word), or at 15 characters per second otherwise (within about half a second).
• A new reply drops the previous reply’s pending actions. When the visitor interrupts the agent, the rest of the reply’s actions are canceled.

​

The spotlight

​

Highlight styles

​

Making sure the visitor can see it

• Fixed or sticky bars, such as a site header, a cookie banner or a chat bubble: the page is scrolled so the element lands in the clear part of the screen, not underneath them.
• Hidden elements, such as a carousel slide that isn’t showing or the contents of a closed accordion, aren’t drawn. The action reports hidden.
• Covered elements, under something floating over the page wherever it scrolls (an open popup, for example), are scrolled to but not drawn. The action reports covered.
• If content loading above the element pushes it off screen after the scroll, the SDK scrolls once more. If a popup opens over the element while it is highlighted, the highlight is removed.

​

Navigation

​

The visitor notice

​

Turn it on

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-page-guide="true"
  data-page-guide-actions="highlight,scroll,navigate"
  data-page-guide-hide=".account-menu,#billing"
  data-page-guide-highlight="soft"
  data-page-guide-color="#0f766e"
></script>

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),
  },
});

​

Configuration reference

​

PageGuideConfig

​

Types

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()

console.log(window.Callers.widget.getPageContext());
// With a programmatic WebCall:
console.log(webCall.getPageContext());

​

Transcript messages

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 }]
    });
  },
});

​

Privacy and security

​

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.

<section data-callers-private>
  <h2>Saved payment methods</h2>
  …
</section>

<nav class="account-menu">…</nav>
<!-- plus hideSelectors: ['.account-menu'] -->

​

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

​

Single-page apps

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

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;
}

​

Tips for pages that guide well

• Give buttons and links clear, visible text or aria-labels. The agent can only point at what it can name, and the spotlight label shows that name to the visitor.
• Use real <button> and <a href> elements, or role="button" / role="link". A clickable <div> without a role is listed as text at best.
• Label landmarks (<nav aria-label="Account">, <section aria-label="Pro plan">). Landmarks are named by their label only, so an unlabeled section contributes nothing.
• Keep the key controls of a page within the first 150 elements, or raise maxElements (up to 300) on dense pages.
• Hide account details, admin panels and anything personal with data-callers-private, even when they contain no form fields.
• Check getPageContext() on every template once. If a button is missing, it’s hidden, inside an iframe or a closed shadow root, or has no name.

​

Try it in the playground

​

In the dashboard

​

Troubleshooting

​

FAQ

​

Related