Identify known users so the widget starts with real customer context.

Use it when

• Your app already knows the current user
• Support should see account history immediately
• You want cleaner CRM and inbox data from day one
• You need to push custom contact or company information into HAL from your product

For trust-sensitive implementations, combine this with full identity verification.

Route

The widget identification route is:

POST https://api.chatwithhal.com/api/widget/identify

Minimum payload

{
  "app_id": "proj_123",
  "visitor_id": "user_456",
  "email": "alice@acme.com"
}

Recommended payload

{
  "app_id": "proj_123",
  "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": {
      "arr_band": "50k-100k",
      "crm_owner": "Sam"
    }
  }
}

Field behavior

• metadata enriches the linked contact record inside HAL
• company.metadata enriches the linked company record
• company.stage can update CRM stage using the project default precedence mode or a per-request override
• company.id links the contact to that HAL company and establishes the active company context for later widget CRM writes
• company_ids can be used to link additional HAL companies even if you do not send a full company object

Identify vs set-properties

Use identify when you are setting or refreshing identity plus CRM context. Use /api/widget/set-properties when the visitor is already identified and you only want to merge extra visitor/contact properties later.

Identify vs track

Use identify and set-properties for current-state attributes. Use /api/widget/track or window.HalWidget.track(...) for point-in-time milestones such as trial-started, plan-upgraded, or deal-risk-changed.

• Attributes answer “what is true about this customer now?”
• Tracked events answer “what happened at this moment?”
• Company events require the visitor to already resolve to a linked company; pass company_id when multiple companies may be linked

What identify unlocks

• The inbox can show the right customer name, email, and linked contact context immediately
• Widget messages can be attached to contact and company records instead of staying anonymous
• Later widget calls like track(), setStage(), and setDeal() can write richer context to the active or explicitly targeted company record

Recommended rollout

• Call identify() after your app knows the authenticated user
• Include email whenever possible so HAL can reliably create or match the contact
• Use company.id when you know the current HAL company record for this logged-in session
• Use company_ids only to attach additional linked companies; it does not replace the active company established by company.id
• Pass the same HAL company ID later as company_id on setStage(), setDeal(), and company-scoped track() calls when the user can switch accounts
• Use set-properties() for incremental product context after identify instead of re-sending the full payload repeatedly

Verification

If identity verification is enabled for the project, include user_hash so HAL can treat the identity as verified. This is the recommended setup when your backend is asserting a signed-in user.

Related docs