Skip to main content
This quickstart gets the chat widget live on your site and connected to a Halo agent. It assumes you’ve already created a workspace at haloagents.ai.

​
What you’ll need

Three things from the dashboard:
ValueLooks likeWhere to find itWhere it goes
Org IDUUIDSetup > InstallFrontend, in the snippet
Widget keyab_live_...Setup > InstallFrontend, in the snippet — publishable, safe to expose
Identity secretha_secret_...Settings > SecurityServer only, used to sign JWTs (optional but recommended for production)
The widget key is like Stripe’s publishable key — designed to live in your HTML. The identity secret is like a Stripe secret key — never put it in client code.

​
1. Install the widget

Paste this before the closing </body> tag on every page where you want the widget to appear: 
<script src="https://cdn.haloagents.ai/sdk/latest/haloagents.umd.js"></script>
<script>
  window.HaloAgents.init({
    orgId: "your-org-id",
    apiKey: "ab_live_xxxxxxxxxxxxxxxx",
  });
</script>
The widget appears in the bottom-right corner immediately. It works with any site — React, WordPress, Shopify, plain HTML — and updates automatically when we ship improvements.
The widget renders inside a Shadow DOM, so it can’t conflict with your page’s CSS.
By default the chat panel never auto-expands on page load. Users with unread messages see a badge dot on the launcher and tap to open. Same shape as Intercom. If you want the panel to auto-expand for returning users (some support-heavy products do), opt in with ui: { autoOpenUnseen: true } and consider adding manualOnPaths so the panel can’t auto-open over auth or checkout flows.

​
2. Identify your user

As soon as you know who the user is (after login), tell Halo so the AI can personalize answers and your team can see who they’re talking to: 
var ha = window.HaloAgents.getInstance();
ha.identify("user_123", {
  name: "Jane Doe",
  email: "[email protected]",
  role: "admin",
  plan: "pro",
});
If you skip identify() (or omit name and email), tickets and conversations show up as “Anonymous” in your inbox. Always pass at least name and email.
If signup and first login are separate (email verification, invites, etc.), widget identify() alone is not enough. Call POST /api/sdk/users/identify from your signup server handler so contacts exist before the user loads the dashboard. See Identify Users → Authenticated apps with delayed first login.
If your users belong to companies, identify those too: 
ha.identifyCompany("company_456", {
  name: "Acme Corp",
  plan: "enterprise",
  industry: "SaaS",
});
The current user is automatically linked to that company.

​
3. Send context (the magic step)

Identifying the user tells Halo who they are. Sending context tells Halo what’s happening for them right now. This is what turns Halo from a chatbot into something that resolves issues without asking clarifying questions. 
ha.setContext("integrations", {
  label: "Connected Integrations",
  type: "integration",
  value: {
    stripe: { connected: true, status: "active" },
    hubspot: { connected: true, status: "error", error: "Token expired" },
  }
});

ha.setContext("usage", {
  label: "This Month's Usage",
  type: "metric",
  value: { api_calls: 1250, api_limit: 5000, plan: "pro" }
});
Now when a user asks “Why isn’t my HubSpot syncing?”, the AI already knows the token is expired and can give specific, actionable next steps. See Send Context for all the context types (list, integration, error, status, config, feature, metric, relationship, custom) and Planning Your Context Strategy for how to decide what to send.

​
4. Try it

Open your site and click the chat bubble in the bottom-right. Send a message like “What can you do?” — the AI should reply using your agent’s default instructions. If you’ve already added knowledge sources and integration data, try product-specific questions and watch the AI use your context to answer. Conversations appear in real time at Inbox > Conversations in the dashboard. If the AI escalates (or the user asks for a human), a ticket is created automatically and routed by your escalation rules.

​
What to do next

Now that the widget is talking to your AI, the highest-leverage things to do are:

Add Knowledge

Crawl your help center, upload files, or write internal docs so the AI has accurate answers to ground itself in.

Configure Your Agent

Edit the agent’s instructions, turn on skills, and set up escalation rules so tickets reach the right teammates.

Connect Email

Forward customer emails into Halo so support questions become tickets your AI and team can handle.

Connect Integrations

HubSpot, Stripe, Slack, Linear, Zoom, and more — each one makes the AI smarter and unlocks new actions.

​
Production-ready installs

For production, you’ll likely want two more things:
  • Identity verification — sign a JWT on your server with the Identity Secret so users can’t impersonate each other. See Identity Verification.
  • Server-side identify at signup — when signup and first session can be days apart, call /api/sdk/users/identify from your signup API (not only widget identify() on login). Pass signed_up_at from your product’s user created_at.
  • Server-side context — sync data from your backend (HubSpot status, Stripe info, integration health) using the REST API so context is always fresh, even when users haven’t loaded the dashboard recently.
Both are covered in the Advanced section.