Widget identification

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

Widget identification is useful when a signed-in customer should be mapped to an existing person or account in HAL.

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_ids can be used to link existing 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.

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.