Skip to main content

​
Interface: CharAgentElement

<char-agent> custom element. Creates an iframe pointing to the SaaS app’s /embed/ entrypoint and relays auth, styles, dark mode, display mode, and MCP messages via postMessage. Uses a unified char-context message with diffing (only changed fields are sent) instead of separate messages per concern.

​
Extends

  • HTMLElement

​
Properties

​
apiBase?

optional apiBase: string
React 19-friendly property form of api-base. Read once during connectedCallback.

​
publishableKey?

optional publishableKey: string
Publishable key for org identification. Set via publishable-key attribute or JS property.

​
Methods

​
attributeChangedCallback()

attributeChangedCallback(name, _oldValue, newValue): void
Reacts to observed attribute updates after iframe readiness. Attributes that affect iframe boot configuration are intentionally ignored after mount (enable-debug-tools, api-base).

​
Parameters

name
string
_oldValue
string | null
newValue
string | null

​
Returns

void

​
connect()

connect(options): boolean
Connect to the Char agent with authentication. The token is stored as a JavaScript property (not as a DOM attribute), preventing exposure to DOM inspection and session replay tools.

​
Parameters

options
ConnectOptions Authentication payload.

​
Returns

boolean true when the payload is accepted; false when validation fails.

​
connectedCallback()

connectedCallback(): void
Mount lifecycle: builds iframe runtime, starts proxying, and starts host observers. The existing runtime is reused when reconnecting during fast detach/reattach cycles.

​
Returns

void

​
disconnect()

disconnect(): boolean
Disconnect from the Char agent. Clears pending auth state and posts a disconnect message to the iframe.

​
Returns

boolean true when the disconnect message was sent; false when the iframe was not ready.

​
disconnectedCallback()

disconnectedCallback(): void
Unmount lifecycle: requests iframe teardown and releases all host resources.

​
Returns

void

​
setAuth()

setAuth(options): boolean
Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.

​
Parameters

options
Auth payload to connect, or null to disconnect. ConnectOptions | null

​
Returns

boolean Result from connect() or disconnect().

​
setHostContext()

setHostContext(hostContext): void
Update the host context sent to the iframe. Only changed fields are transmitted (diffing pattern).

​
Parameters

hostContext
CharHostContext Partial host context patch to merge and emit.

​
Returns

void