TIP

Host-page JavaScript API for agent-widget.js.

Related: Function Tool Call Setup for signed-in visitor auth (setAuth), website context (setContext), and {host.*} tokens.

This page documents the public API exposed by agent-widget.js on the host (customer-facing) page.

Audience	Difficulty
Website / app integrators	Intermediate

When is AgentWidget available?

INFO

window.AgentWidget is created as soon as the embed script runs successfully. Commands called before the iframe is ready are queued and flushed on ready.

Condition	Result
Script tag includes valid `data-pid` and `data-cid`, and `src` loads	`window.AgentWidget` exists
Script missing `data-pid` / `data-cid`, or invalid `src`	API is not created (console warning)
Immediately after script load	Methods exist; calls to the iframe are queued until ready
After the `ready` event / `AgentWidget.isReady() === true`	Iframe is ready; queued commands flush
After `AgentWidget.destroy()`	API no longer works on that page
WhatsApp or admin builder	Not available - host SDK runs only on the embedded web page

WARNING

Do not call AgentWidget methods until the script has loaded. Guard with window.AgentWidget (see safe pattern below).

Embed the script

Attribute	Required	Description
`src`	Yes	URL of `agent-widget.js` on your app origin
`data-pid`	Yes	Project ID
`data-cid`	Yes	Chatbot / agent ID

After load, the script handshakes with the widget backend, renders the chat bubble, and exposes window.AgentWidget.

Safe ready pattern

NOTE

You may call setAuth, setContext, and identify before ready. The SDK queues those messages. Prefer waiting for ready when you need to know the chat session can use them.

Global object

Global: window.AgentWidget

Property	Type	Description
`version`	`number`	SDK version (currently `2`)
`projectId`	`string`	From `data-pid`
`chatbotId`	`string`	From `data-cid`

Lifecycle

Method	Purpose
`AgentWidget.open()`	Opens the chat panel
`AgentWidget.close()`	Closes the chat panel
`AgentWidget.toggle()`	Toggles open / closed
`AgentWidget.destroy()`	Removes bubble, iframe, tips, listeners, and pending work

State

Method	Returns	Purpose
`AgentWidget.isOpen()`	`boolean`	Whether the panel is open
`AgentWidget.isReady()`	`boolean`	Whether the iframe has signaled READY
`AgentWidget.getState()`	`object`	`{ open, ready, initialized, destroyed, appearance }`

Events

The SDK has an in-JS emitter and also dispatches DOM CustomEvents named AgentWidget:<eventName> on window.

Method	Purpose
`AgentWidget.on(eventName, handler)`	Subscribe; returns an unsubscribe function
`AgentWidget.once(eventName, handler)`	Subscribe once; returns unsubscribe
`AgentWidget.off(eventName, handler)`	Remove a handler

Common events

Event	When
`init`	Handshake / appearance loaded
`ready`	Iframe READY; safe for iframe-dependent work
`open` / `close`	Panel opened / closed
`destroy`	After `destroy()`
`resize`	Desktop width changed via `setWidth` / `resetWidth`
`request_identity`	Iframe asks for current logged-in user
`require_login`	Agent asks the host to show login
`request`	Iframe needs a host action (e.g. login tool); respond with `sendResponse`
(custom)	Any event name the iframe or host emits

Method	Purpose
`identify(user)`	Send user profile for personalization (not a substitute for auth)
`setAuth(auth)`	Set visitor auth used for signed-in Function Tool Calls and gated flows
`clearAuth()`	Clear visitor auth (logged out)
`setContext(context)`	Page / app context for `{host.*}` tokens in Function Tool Call
`setRuntimeContext(context)`	Internal / advanced runtime context channel
`sendMessage(text, meta?)`	Send a user message into the chat
`prefillMessage(text, options?)`	Prefill the composer (`options.focus` defaults to `true`)
`clearInput()`	Clear the composer text
`emitEvent(name, payload?)`	Emit a custom event into the widget runtime
`resetSession()`	Clear / rotate the conversation session
`setWidth(width)`	Desktop panel width (mobile stays full screen)
`resetWidth()`	Reset desktop width to the SDK default

Identity vs auth vs context

API	Use for	Function Tool Call
`identify(user)`	Display name, email, CRM id for personalization	Does not unlock signed-in visitor tools by itself
`setAuth({ kind, ... })`	Access token / credentials for APIs acting as the visitor	Required for Signed-in visitor tools
`clearAuth()`	Logout	Signed-in visitor tools are omitted until auth is set again
`setContext({ ... })`	Non-secret page values (`project_id`, `store_id`, ...)	Becomes `{host.key}` after you list keys under From your website

WARNING

Do not put secrets in setContext. Use setAuth for visitor tokens, or stored credentials in Function Tool Call for shared API keys.

Auth shapes

Bearer token (most common)

Basic auth

API key header

API key query

Custom headers

Cookie-based auth

Context example (Function Tool Call)

In the tool builder, add those keys under From your website, then use {host.project_id} (and so on) in the URL, headers, query, or body.

See Function Tool Call Setup for sample use cases.

Other examples

Initial identity (request_identity)

When the iframe loads, listen and reply with the current user (or null if logged out):

For signed-in Function Tool Calls, also call setAuth with the access token when the user is logged in (on page load and after login / refresh).

Require login (require_login)

When the agent needs the visitor to sign in:

Iframe to host requests

When the agent needs the host page to do something (for example login), the SDK emits request. Reply with sendResponse.

AgentWidget.sendResponse(requestId, payload?, success?, error?)

Argument	Type	Description
`requestId`	`string`	From the `request` event
`payload`	`any`	Success payload
`success`	`boolean`	Defaults to `true`
`error`	`object` or `null`	Failure details

Recommended integration

Embed the script

Add agent-widget.js with data-pid and data-cid on the host page.

Wait for ready

Use AgentWidget.once("ready", ...) or whenAgentWidgetReady.

Set identity, auth, and context

Call identify, setAuth, and setContext when the visitor session and page context are known.

Handle login events

Listen for request_identity, require_login, and request as needed by your product flows.

Open the widget from your UI

Call AgentWidget.open() from buttons or other triggers.

NOTE

For Function Tool Call setup (inputs, auth modes, {host.*} mapping), see Function Tool Call Setup.

Summary

Category	API
Availability	Script with `data-pid` + `data-cid` creates `window.AgentWidget`; wait for `ready` when needed; gone after `destroy()`
Lifecycle	`open`, `close`, `toggle`, `destroy`
State	`isOpen`, `isReady`, `getState`
Events	`on`, `once`, `off`
Auth	`setAuth`, `clearAuth`
Context	`setContext`, `setRuntimeContext`
Identity	`identify`; events `request_identity`, `require_login`
Chat	`sendMessage`, `prefillMessage`, `clearInput`, `resetSession`
Layout	`setWidth`, `resetWidth`
Host replies	`sendResponse` (to `request` events)
Custom	`emitEvent`

Agent Widget JavaScript SDK

When is AgentWidget available?

Embed the script

Safe ready pattern

Global object

Lifecycle

State

Events

Common events

Host commands (page to widget)

Identity vs auth vs context

Auth shapes

Context example (Function Tool Call)

Other examples

Iframe to host requests

Recommended integration

Summary

Agent Widget JavaScript SDK

When is AgentWidget available?#

Embed the script#

Safe ready pattern#

Global object#

Lifecycle#

State#

Events#

Subscribe#

Common events#

Host commands (page to widget)#

Identity vs auth vs context#

Auth shapes#

Context example (Function Tool Call)#

Other examples#

Identity and login flows#

Iframe to host requests#

Recommended integration#

Summary#

When is AgentWidget available?

Embed the script

Safe ready pattern

Global object

Lifecycle

State

Events

Subscribe

Common events

Host commands (page to widget)

Identity vs auth vs context

Auth shapes

Context example (Function Tool Call)

Other examples

Identity and login flows

Iframe to host requests

Recommended integration

Summary