Install the widget to capture support signals and customer conversations.

Basic install

Add the embed script to your site after you create a project in HAL.

<script
  src="https://api.chatwithhal.com/widget.js"
  data-project-id="your-project-id">
</script>

Set widget language

You can force the widget UI language from your app in two ways: directly on the embed script with data-locale, or through the JavaScript init() API.

Option 1: Use data-locale on the script tag

<script
  src="https://api.chatwithhal.com/widget.js"
  data-project-id="your-project-id"
  data-locale="de">
</script>

Option 2: Set locale in HalWidget.init()

<script src="https://api.chatwithhal.com/widget.js"></script>
<script>
  window.HalWidget.init({
    projectId: 'your-project-id',
    locale: 'de'
  });
</script>

• locale should be a supported language code such as en, de, fr, or sl
• An explicit locale from the embed code or init() overrides the widget's default language setting in HAL
• If you do not set a locale, HAL falls back to the widget default language and then the browser language

What the widget feeds

• Customer conversations in Inbox
• Repeated support themes and friction signals
• Help-center usage and deflection context
• Visitor identity data when configured
• Product and business milestone events when your app calls window.HalWidget.track(...)

Push visitor and CRM context

If your app already knows the signed-in user, identify them before they start chatting so HAL can attach the conversation to the right contact and company records.

await window.HalWidget.identify({
  visitor_id: 'user_456',
  user_id: 'user_456',
  email: 'alice@acme.com',
  name: 'Alice',
  metadata: {
    plan: 'enterprise',
    role: 'admin'
  },
  company: {
    id: 'acme',
    name: 'Acme Inc',
    stage: 'Qualified',
    metadata: {
      crm_owner: 'Sam',
      arr_band: '50k-100k'
    }
  }
});

• metadata merges into the linked contact record
• company.metadata merges into the linked company record
• company.stage can move the company in CRM using the configured stage precedence rules
• company.id establishes the active company context for later widget CRM writes
• company_ids can link existing HAL companies when you do not want to send a full company object

CRM stage sync

When the widget sends CRM stage information, HAL treats it as a lower-authority signal by default. If your sales team has already moved a company to a later stage, widget updates will not downgrade it.

• Default: advance_only keeps manual sales progress authoritative
• Optional: exact applies the requested stage exactly, including intentional downgrades
• Where to set it: Settings → Widget → CRM Stage Sync for the project default, or per request in the widget/API payload

Use exact only when your own backend is the CRM system of record and should override later stages.

Track product milestones

Use window.HalWidget.track(name, value?, options?) for point-in-time events such as plan changes, onboarding completion, or account risk updates. This is intentionally simpler than a full analytics schema: send a required event name and an optional scalar value.

await window.HalWidget.track('trial-started');
await window.HalWidget.track('seats-updated', 12);
await window.HalWidget.track('plan-upgraded', 'pro');
await window.HalWidget.track('deal-risk-changed', 'high', { entity: 'company' });

• Use track() for milestones and product signals, not raw UI clickstream
• Use identify() and set() for current-state attributes such as plan, role, or feature flags
• Company events require the visitor to already resolve to a linked company, which usually means identifying with an email first
• Pass company_id on company-scoped events when the contact can be linked to multiple companies
• Tracked events appear in contact timelines, company activity, and inbox context

Push deal value from your app

If your product already knows the value of a trial, quote, or expansion, you can push that data into HAL from the widget script after the visitor has been identified.

<script
  src="https://api.chatwithhal.com/widget.js"
  data-project-id="your-project-id">
</script>
<script>
  await window.HalWidget.identify({
    email: 'buyer@example.com',
    company: { id: 'acme', name: 'Acme' }
  });

  await window.HalWidget.setDeal({
    company_id: 'acme',
    deal_value: 12000,
    stage_name: 'Qualified'
  });
</script>

• deal_value writes to the company record in HAL CRM
• stage_name is optional and follows the same precedence rules as setStage()
• company_id is optional but recommended whenever your app already knows the current HAL company ID
• The visitor must already be linked to a contact/company, which usually means calling identify() with an email first

Reset identity on logout

If your app supports login/logout, reset the widget when the user signs out. This clears the current browser-side widget identity and remounts the widget with a fresh anonymous visitor so the next user can be identified cleanly.

// After your app logs the user out
await window.HalWidget.resetIdentity();

// Later, after a different user logs in
await window.HalWidget.identify({
  user_id: 'user-456',
  email: 'new-user@example.com',
  user_hash: 'server-generated-hmac'
});

• Use this on shared browsers or any SaaS app where different accounts can use the same device
• Call it before identifying the next user
• It resets the client-side widget identity; it does not delete CRM records or historical conversations in HAL

Recommended rollout

Related docs