Skip to main content
The hosted website widget connects visitors to a saved PyAI Agent without putting an API key in your site or requiring you to run a token server.

Try the managed widget

Open the website voice assistant demo. The page embeds the managed widget for Lantern Desk, a fictional appointment-reminder service. Opening the page loads the launcher. Starting a conversation requests microphone access and uses the widget’s daily allowance. Both daily limits reset at 00:00 UTC. On 20 November 2026 the public page rendered the launcher, and the service issued a session for its exact website origin. The v12 browser connection closed before audio was exchanged. A spoken answer and interruption on this managed demo still need live verification. The earlier recorded conversation used the custom browser client described below.

Get the snippet for a published widget

Connect to the intended project with only widgets:read. Verify the project ID and environment with whoami, then ask your coding agent “Show the embed snippet for my already published website voice widget.” The agent calls list_published_website_widgets and returns the saved widget’s snippet verbatim. If several match, choose by agent name or website origin. An empty result means this project has no published widget visible to the connection. This lookup changes no settings and starts no visitor session.

Publish from a coding agent

A saved voice agent supplies the persona, greeting and voice. Its managed widget supplies the website origin, session limits and embed snippet. The hosted widget sends visitor microphone audio to PyAI. If visitor audio must stay on the device, the hosted widget cannot meet that requirement. Stop before drafting or publishing. A separate local recording can have its own upload restriction. A widget can limit how many sessions start each day. Session length and charges can vary. If publication requires a hard total spend limit, such as $10 over the life of the widget, stop before publishing. The widget has no setting that enforces this amount.
  1. Call whoami and confirm the intended project, environment and billing context. To reuse an agent, supply its ID. To create one, use create_agent with a voice and persona. Widget management requires its own permissions, even if the connection can create an agent.
  2. Use draft_website_widget with the agent ID and a body like the one below. Replace the example origin with the exact HTTPS origin approved by the site owner. Choose both limits explicitly. The draft cannot start a visitor session.
  3. Use preview_website_widget and show the project, agent, allowed origin, both limits, readiness and snippet to the person authorizing publication. These limits count visitor sessions per UTC day. The account’s prices and credit policy determine cost.
  4. Wait for approval of that preview. Then call publish_website_widget with the agent ID and {"approved": true, "revision": "<revision from the approved preview>"}. Return the response’s snippet verbatim for insertion on the approved site. Publishing starts no session. If a write times out or the draft changes, preview the saved state before deciding what to do. A changed revision needs fresh approval.
An existing connection may need fresh consent for these permissions. A read-only grant can preview a widget for a supplied agent ID. To revise an unpublished draft, pass its latest expected_revision when drafting. To manage an already published widget, use Website & phone.

Publish in the console

  1. Open Agents, choose an Agent, then open Website & phone.
  2. Add every exact website origin that may host the widget, for example https://www.example.com. Production origins must use HTTPS.
  3. Choose the launcher, position, colors, labels, and branding.
  4. Publish and copy the generated snippet:
The widget id is an opaque public identifier. It is not an organization, project, Agent, or key id.

Appearance and actions

Open Agents → your agent → Website & phone to change the launcher, position, colors, labels, and branding. Use the editor’s supported URL, telephone, or event actions. Add exact allowed origins, publish, and copy the generated snippet to your site. The widget does not execute custom JavaScript or customer-provided HTML. Change the voice, greeting, prompt, and recording disclosure on the agent profile, not in the script tag. Use the browser client guide when you need to own the complete media interface.

Security model

On page load, v12 resolves only safe display configuration. When a visitor starts a call, PyAI checks the exact browser Origin, the widget and Agent status, account credit, and daily widget/IP limits. It then mints one short-lived key with only omni:session, concurrency 1, the visitor origin, and the Agent as its session label. The browser never receives a long-lived credential. If recording is enabled on the Agent, the widget shows the Agent’s consent notice before requesting microphone permission.

Runtime errors

Listen for pyai:widget-error. Its detail is a stable, sanitized object:
Supported codes are mic_permission_denied, unsupported_browser, origin_not_allowed, credit_exhausted, daily_cap_exceeded, session_unavailable, websocket_failed, config_unavailable, and consent_required. Error events never include session tokens, internal identifiers, upstream responses, or visitor addresses. Listen for pyai:widget:transcript to receive the same sanitized transcript rows shown in the widget. The current public capability is capabilities.transcript: "caller": production emits caller text only, so the widget never fabricates Agent text from audio. detail.version is 1; its fields are role, text, and final. Partial caller updates replace one open row and freeze once at the response boundary. A future runtime can advertise a broader transcript capability without changing this versioned event envelope. Listen for pyai:widget:state to receive semantic listening, thinking, and agent_speaking transitions derived from session controls and response audio. Neither event nor the UI exposes raw frames, tool arguments, tokens, or identifiers. For a strict Content Security Policy, allow the versioned script from https://cdn.pyai.com, API requests to https://api.pyai.com, and voice WebSockets to wss://api.pyai.com. The runtime does not evaluate strings as code or inject customer-provided HTML. If your policy requires nonces for inline styles, put a nonce on the script element; v12 copies it to its style element.

Opening audio and older embeds

Widget v12 keeps the consent line and turn-0 greeting isolated from browser speaker echo. It buffers server PCM until the playback graph is running, sends real-time digital silence instead of microphone/self-audio through the opening drain, and restores normal barge-in on later replies. Versioned widget URLs are immutable. Existing v1-v11 embeds do not update in place. Replace their script URL with /widget/v12/pyai-widget.js; v12 is the current published widget. v12 retains protected opening and browser-valid closes, and narrowly normalizes the deployed playback-position advisory while older engine revisions drain. If you operate your own session broker or media UI, follow the browser voice agent guide and mint a short-lived, origin-locked session token with POST /v1/omni/sessions. Never put a secret key in browser code.

Reproduce a website receptionist journey

Tested custom browser path — 18 November 2026

The existing browser concierge example now includes a local, authenticated Lantern Desk demonstration. A real browser connected to the public Omni service with a short-lived origin-locked token. Four saved synthetic visitor clips entered its microphone MediaStream; replies used its normal Web Audio playback graph. No phone number or carrier was used. The successful session lasted 54.6 seconds. It answered from the supplied fictional facts, captured four team members and a need for reminders, requested confirmation, saved exactly one enquiry on the example backend, and then answered an interruption with “Four people are on your team.” The backend returned its durable receipt before the success reply. Scheduled playback was cancelled 269 ms after the injected interruption began, with a 15 ms fade. That is one browser control observation, not acoustic latency or a percentile. A reviewer confirmed the recording is clear and that the interruption works.
  • Wrong origin: a real WebSocket attempt from a different origin returned HTTP 403.
  • No exposed API secret: the browser session response contained no long-lived key; the page received only the short-lived token.
  • Exhausted credits: the actual demo handler was tested against a mocked upstream HTTP 402. No live account was drained; this is not live billing proof.
  • First failed session retained: native tool arguments arrived as JSON text, which the original example rejected. The backend now accepts and validates either JSON text or an object. The agent correctly withheld a completion claim on that failure. A separate unsupported product claim was removed by restricting the demo instructions to its explicit facts.
Listen to the recorded conversation and inspect the result and limitations. This validates the custom browser example with inline facts and a local test action. It does not qualify the separately hosted widget, indexed knowledge retrieval, a physical microphone, echo handling, or general conversational accuracy. Inspect the configured voice acknowledgement: this successful run used the server’s Standard default, stock_sarah_style2; a catalog entry alone does not establish that a requested voice tier was selected in a session.

Hosted widget acceptance scenario

No phone number or carrier is needed. Use an isolated, authorized test Agent and a confirmed usage budget. This is a prepared acceptance scenario, not a claim that the managed hosted widget completed the custom-client test above.
  1. Add a small fictional knowledge document: “Lantern Desk provides appointment reminders. The demo supports teams of up to ten users. The demonstration never books a real appointment.” Confirm indexing completes.
  2. Set the Agent’s instructions to answer only from that document, ask the visitor’s team size and whether they need reminders, and request confirmation before saving an enquiry. Keep recording disabled unless explicitly needed.
  3. Register one server tool, save_demo_enquiry, against an authenticated test backend. Accept only team_size and needs_reminders; validate them, deduplicate by the tool call ID, and return a stable receipt. Use a test store, with no email, CRM or calendar side effects. A tool’s name in the prompt does not connect a backend.
  4. Publish the widget to one exact HTTPS test origin using the steps above. Capture the widget version, Agent configuration, project, browser, region, request IDs and tool receipt. Keep tokens and personal data out of the report.
  5. Use the same script below when an audio run is authorized. Retain the recording only under the test project’s agreed retention policy.
Test denied paths separately before running that script:
  • Wrong origin: request widget configuration/session from an origin absent from the allowlist. Expect denial, no session token and no voice connection.
  • Exhausted credit: use an isolated fixture or test account with exhausted credit. Expect credit_exhausted, no voice connection and no automatic retry. Do not change the balance of an active customer account for this test.
  • Credential exposure: inspect the HTML, public configuration, error events and browser storage. They must contain no long-lived API key. A short-lived session credential is expected only after successful admission; do not save it in screenshots, analytics or logs.
  • Backend rejection or timeout: do not announce a saved enquiry or repeat an uncertain write. Reconcile using the original tool call ID and receipt.
The existing widget handler tests passed exact-origin rejection, exhausted-credit rejection and secret-free public configuration on 17 November. These used local fixtures, not customer traffic. They do not prove audible interruption, a full knowledge-to-tool journey, or enforcement by a customer’s own backend. Those checks remain pending for the scenario above; no new audio was generated.