Skip to main content

​
Instance methods

After calling HaloAgents.init(), you get back an instance with these methods:

​
Chat

​
sendMessage
(text: string) => void
Send a message programmatically. The message appears in the chat widget and is processed by the AI agent.
ha.sendMessage("How do I connect my Stripe account?");
​
openChat
() => void
Open the chat widget panel. Fires onChatOpen (if configured) on the closed→open transition. A no-op when the panel is already open.
ha.openChat();
​
closeChat
() => void
Close the chat widget panel. Fires onChatClose (if configured) on the open→closed transition. A no-op when the panel is already closed.
ha.closeChat();

​
User identification

​
identify
(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.
ha.identify("user_123", { name: "Jane", role: "admin" });

// With identity rotation
ha.identify("user_123", { plan: "enterprise" }, { userToken: freshJwt });
​
identifyCompany
(companyId: string, traits?: CompanyTraits) => void
Identify the current user’s company.
ha.identifyCompany("company_456", { name: "Acme Corp", plan: "pro" });

​
Context

​
setContext
(key: string, entry: ContextEntry) => void
Set a structured context entry. See Send Context.
ha.setContext("errors", {
  label: "Current Issues",
  type: "error",
  value: [{ area: "billing", message: "Payment failed" }]
});
​
clearContext
(key?: string) => void
Remove a context entry by key, or clear all context if no key is provided.
ha.clearContext("errors");
ha.clearContext();

​
UI highlights

​
highlightElement
(selector: string, options?: HighlightOptions) => void
Highlight a DOM element. The AI can also trigger highlights automatically when guiding users through your UI.
ha.highlightElement("#settings-btn", {
  color: "#18181b",
  label: "Click here",
});
​
clearHighlights
() => void
Remove all active element highlights.
ha.clearHighlights();

​
Lifecycle

​
destroy
() => 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.
ha.destroy();

​
Diagnostics

​
debug
() => 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 (userToken, apiKey) are reduced to presence flags rather than echoed.
const info = HaloAgents.getInstance()?.debug();
// Or send the structured snapshot to your own support tooling:
fetch("/internal/halo-debug", { method: "POST", body: JSON.stringify(info) });
See Troubleshooting for what each field means and how to read the output.

​
Static methods

​
HaloAgents.init()

HaloAgents.init(config: HaloAgentsConfig): HaloAgentsInstance
Initialize Halo and return the instance. Calling 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()

HaloAgents.getInstance(): HaloAgentsInstance | null
Get the current instance, or null if not initialized. Useful for accessing the instance from different parts of your app: 
var ha = window.HaloAgents.getInstance();
ha?.setContext("page", {
  label: "Current Page",
  type: "status",
  value: "settings/integrations"
});

​
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.