Instance methods
After callingHaloAgents.init(), you get back an instance with these methods:
Chat
(text: string) => void
Send a message programmatically. The message appears in the chat widget and is processed by the AI agent.
() => void
Open the chat widget panel. Fires
onChatOpen (if configured) on the closed→open transition. A no-op when the panel is already open.() => void
Close the chat widget panel. Fires
onChatClose (if configured) on the open→closed transition. A no-op when the panel is already closed.User identification
(userId: string, traits?: UserTraits, identity?: { userToken?: string }) => void
Identify the current user. The optional third argument lets you rotate the signed identity proof at the same time (e.g. when refreshing a JWT). The new token is forwarded on every subsequent SDK request. See Identify Users and Identity Verification.
(companyId: string, traits?: CompanyTraits) => void
Identify the current user’s company.
Context
(key: string, entry: ContextEntry) => void
Set a structured context entry. See Send Context.
(key?: string) => void
Remove a context entry by key, or clear all context if no key is provided.
UI highlights
(selector: string, options?: HighlightOptions) => void
Highlight a DOM element. The AI can also trigger highlights automatically when guiding users through your UI.
() => void
Remove all active element highlights.
Lifecycle
() => void
Unmount the widget, stop event tracking, and clean up all resources. Call this when the user logs out or navigates away in a SPA.
Diagnostics
() => DebugInfo
Print a structured snapshot of the SDK’s runtime state to the console AND return it as an object. Use this as the first step when something seems wrong. The snapshot is safe to share with support: sensitive fields (See Troubleshooting for what each field means and how to read the output.
userToken, apiKey) are reduced to presence flags rather than echoed.Static methods
HaloAgents.init()
init() a second time without first calling destroy() is a no-op: it logs a console warning and returns the existing instance. Call destroy() first if you actually want to re-initialize with new config.
See Configuration for the full config schema.
HaloAgents.getInstance()
null if not initialized. Useful for accessing the instance from different parts of your app:
Where to go next
Customize the Widget
Hide the trigger, open programmatically, theme, and use UI highlighting.
Send Context
Push structured user state to the AI.