` that you place in your page. | You want the agent embedded in a specific section (landing-page hero, support tab, etc.). | | **Headless** | No UI. Only the audio/chat pipeline plus a JavaScript API on `window.DograhWidget`. | You want full control over the UI — your own buttons, design system, framework state, animations. | ## Prerequisites These apply to all three modes: * **Voice widgets:** serve your page over **HTTPS** or from `http://localhost`. Browsers refuse microphone access on plain HTTP origins or `file://`. Chat widgets have no microphone requirement, though HTTPS is still recommended. * If you set **Allowed Domains** in the dashboard, include your test origin (e.g. `localhost`) — otherwise the widget's requests are rejected. Leave the list empty to allow all domains. * The embed snippet you copy from the dashboard is a single ` ``` Because it's built in JavaScript at page load, you can put anything your page knows in it — a logged-in customer's name, their plan, cart contents. Replace the object inside `JSON.stringify(...)` in the generated snippet, for example: ```js theme={null} { customer_name: currentUser.firstName, plan: currentUser.plan, cart: { items: cart.length, total: cart.total } } ``` Each key is then available in any node prompt as `{{initial_context.}}`: ```text theme={null} Greet {{initial_context.customer_name | there}} and mention their {{initial_context.plan}} plan. ``` Values can be strings, numbers, booleans, or nested objects. This works for voice and chat widgets alike, and the values are recorded on the conversation so you can see what the agent was given. ### Update context after the page loads The attribute is fixed at page load, which doesn't fit a single-page app — the visitor logs in, changes route, or fills a cart long after the snippet ran. For that, call `setContext()`: ```js theme={null} window.DograhWidget.setContext({ customer_name: user.firstName, plan: user.plan }); ``` Each call merges into the context already collected, so you can add details as they arrive and re-send a name to correct it. `getContext()` returns the current set. Context is read when a conversation starts, so `setContext()` applies to the **next** conversation — calling it mid-call or mid-chat doesn't change the one in progress (the widget logs a console warning if you do). For chat widgets, "next" includes the fresh conversation started by **Start new chat** after a session expires. The widget script loads asynchronously, so `window.DograhWidget` may not exist yet when your app's code first runs. Call `setContext()` from an event that fires after load — a `window.load` listener, or a user action like clicking your own "Chat with us" button. See [Lifecycle callbacks](#lifecycle-callbacks-all-modes) for the same timing rule. Use whichever fits: `data-dograh-context` for what the page knows at render, `setContext()` for what it learns later. They merge, and `setContext()` wins on a repeated name. Context comes from the page, so a visitor can both read it and change it before it reaches your agent. Never pass secrets, and don't let it gate what the agent will do or disclose — treat `plan: "pro"` as a hint for phrasing, not proof of entitlement. For data the agent must trust, pass an opaque id like `customer_id` and let Dograh fetch the real details from your API with [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch). Limits, applied per conversation: up to 50 variables, 64 characters per name, 2000 characters per value, and 8 KB in total. Anything past a limit is dropped and the conversation still starts. The names `provider` and `runtime_configuration` are reserved and ignored. ## Floating Widget

Floating widget shown in the corner of a host page

Renders a pill-shaped button anchored to a corner of the page. * **Voice:** clicking the button (microphone icon + text) starts a call; clicking again ends it. The button auto-updates its label and color across the call lifecycle: configured text → "Connecting…" → "End Call" → "Retry" on failure. * **Chat:** clicking the button (chat icon + text) opens a chat panel anchored to the same corner; the agent greets the visitor and the conversation happens in the panel. Clicking the button (or the panel's ×) closes the panel without ending the conversation — reopening shows the same transcript. Configure **Button Text**, **Button Color**, and **Position** (top/bottom + left/right) from the dashboard. The host page writes no JavaScript — pasting the embed snippet is the entire integration. If you want to subscribe to call lifecycle events (e.g. analytics), see [Lifecycle callbacks](#lifecycle-callbacks-all-modes) below ## Inline Component

Inline widget rendered inside a page section

Renders a panel inside a `

` you place in your page. * **Voice:** a status panel (status icon + status text + CTA button). Status changes update the panel in place. * **Chat:** a call-to-action screen first; clicking the button replaces it with a chat panel that fills the container. No extra JavaScript is needed. Configure **Button Text**, **Button Color**, and **Call to Action Text** from the dashboard. ### Plain HTML Place a container `

` where you want the widget to render. The widget auto-attaches to it. ```html theme={null}

``` ### React Because React mounts after the widget script may have already loaded, integrate via `initInline` on first mount and `refresh` on remount. Poll for `window.DograhWidget` to handle the async script load. ```tsx theme={null} import { useEffect } from 'react'; declare global { interface Window { DograhWidget?: { initInline: (options: { container: HTMLElement }) => void; refresh: () => void; getState: () => { isInitialized: boolean }; }; } } export function Assistant() { useEffect(() => { let retries = 0; const tryInit = () => { const container = document.getElementById('dograh-inline-container'); if (window.DograhWidget && container) { const { isInitialized } = window.DograhWidget.getState(); if (isInitialized) window.DograhWidget.refresh(); else window.DograhWidget.initInline({ container }); } else if (retries++ < 50) { setTimeout(tryInit, 100); } }; tryInit(); }, []); return

; } ``` ## Headless Mode

In Headless mode the widget injects no UI of its own. You render whatever buttons, banners, or chat interfaces you want, and drive the agent through the JavaScript API. ### JavaScript API (voice widgets) | Method / Callback | Description | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `window.DograhWidget.start()` | Begin a voice call. Must be called from inside a user-gesture handler (e.g. `click`) so the browser grants microphone access. | | `window.DograhWidget.end()` | End the active call. | | `window.DograhWidget.onCallStart(cb)` | Fires when `start()` is invoked (status `connecting`). No payload. | | `window.DograhWidget.onCallConnected(cb)` | Fires when the WebRTC connection is established. Payload: `{ agentId, workflowRunId, token }`. | | `window.DograhWidget.onCallDisconnected(cb)` | Fires only if the call had connected, when teardown runs. Payload: `{ agentId, workflowRunId, token, durationSeconds }`. | | `window.DograhWidget.onCallEnd(cb)` | Fires whenever the call session is torn down (including failed-to-connect attempts). No payload. | | `window.DograhWidget.onStatusChange(cb)` | Fires on every status change. Callback receives `(status, text, subtext)`. Status values: `idle`, `connecting`, `connected`, `failed`. | | `window.DograhWidget.onError(cb)` | Fires on errors (mic permission denied, server error, etc.). Callback receives an `Error` object. | | `window.DograhWidget.setContext(vars)` | Merge visitor context for the next call — see [Pass context to the agent](#pass-context-to-the-agent). Works in every embed mode, not just headless. | All `on*` setters are single-listener — calling the same one again replaces the previous handler. ### JavaScript API (chat widgets) | Method / Callback | Description | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `window.DograhWidget.startChat()` | Start a conversation. The agent's greeting arrives via `onMessage`. | | `window.DograhWidget.sendMessage(text)` | Send a visitor message. Returns a Promise that resolves with the updated transcript (array of turns), or `null` if the message couldn't be delivered. | | `window.DograhWidget.getMessages()` | Current transcript as an array of turns: `{ id, status, user_message, assistant_message }`, each message being `{ text, created_at }`. | | `window.DograhWidget.onMessage(cb)` | Fires once per new agent reply. Callback receives `(text, turn)`. | | `window.DograhWidget.onChatStateChange(cb)` | Fires on every chat state change. States: `idle`, `starting`, `ready`, `waiting` (agent is replying), `ended`, `expired`, `error`. | | `window.DograhWidget.onError(cb)` | Fires on errors. Callback receives an `Error` object. | | `window.DograhWidget.setContext(vars)` | Merge visitor context for the next conversation — see [Pass context to the agent](#pass-context-to-the-agent). Works in every embed mode, not just headless. | In chat mode `start()` aliases `startChat()` and `end()` is a no-op teardown (chat sessions need none), so generic snippets keep working. Sends are serialized — `sendMessage` while a reply is pending (`waiting`) resolves to `null`. ```html theme={null}

``` **About timing.** The widget script loads asynchronously, so `window.DograhWidget` may not exist at the moment your inline ` ``` ### React + TypeScript ```tsx theme={null} import { useEffect, useState } from 'react'; type CallStatus = 'idle' | 'connecting' | 'connected' | 'failed'; declare global { interface Window { DograhWidget: { start: () => void; end: () => void; onStatusChange: (cb: (status: CallStatus, text?: string, subtext?: string) => void) => void; onError: (cb: (err: Error) => void) => void; }; } } export function TalkButton() { const [status, setStatus] = useState('idle'); useEffect(() => { window.DograhWidget.onStatusChange((s) => setStatus(s)); window.DograhWidget.onError((err) => console.error('Dograh error:', err.message)); }, []); const isLive = status === 'connected' || status === 'connecting'; const label = { idle: 'Talk to AI', connecting: 'Connecting…', connected: 'End Call', failed: 'Retry' }[status]; return ( ); } ``` `start()` must run inside a real user-gesture handler (`click`, `touchend`, etc.). Browsers refuse to grant microphone access to scripts that request it outside of one — calling `start()` from a `setTimeout` or on page load will fail with a permission error. ## Lifecycle callbacks (all modes) The `on*` callbacks in the [Headless JavaScript API](#javascript-api-voice-widgets) work in **all three embed modes**, not just Headless. Use them for analytics or to trigger UI in the host page even when the widget is rendering its own UI (Floating or Inline). The call callbacks (`onCall*`) fire for voice widgets; for chat widgets use `onMessage` and `onChatStateChange` the same way. ```js theme={null} window.DograhWidget.onCallConnected(({ agentId, workflowRunId }) => { analytics.track('voice_call_started', { agentId, workflowRunId }); }); window.DograhWidget.onCallDisconnected(({ workflowRunId, durationSeconds }) => { analytics.track('voice_call_ended', { workflowRunId, durationSeconds }); }); ``` `onCallConnected` and `onCallDisconnected` only fire when the call actually establishes a media connection — failed-to-connect attempts (e.g. denied mic, network failure) don't trigger them, so analytics stay clean.