Visitor and conversation endpoints sit underneath the widget and inbox workflow.

Typical uses

• Create or update visitor identity and profile data
• Push custom contact metadata from your product into HAL
• Link a visitor to one or more CRM companies
• Update company stage and company metadata during identify

The route most customers want

If you want your own app or backend to send custom contact or company information into HAL, use POST /api/widget/identify.

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

This route is the supported integration surface for enriching a widget visitor with known customer identity and CRM context.

Request fields

• app_id or project_id: the HAL project
• visitor_id: your stable identifier for the current visitor session or user
• user_id, email, name: known identity fields
• metadata: custom contact-level properties to merge into HAL contact context
• company_ids: one or more existing HAL company IDs to link
• company: optional company object with id, name, stage, and metadata
• stage_update_mode: optional override for CRM stage precedence
• user_hash: optional verification signature when identity verification is enabled

What HAL does with the data

• metadata is merged into the linked contact metadata when the visitor can be mapped to a contact
• company.metadata is merged into the linked company metadata
• company.stage can move the linked company in CRM, subject to stage precedence rules
• company_ids links the visitor’s contact to existing HAL companies

Example request

{
  "app_id": "proj_123",
  "visitor_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"
    }
  }
}

Use set-properties for follow-up updates

If you already identified the visitor and only need to append or refresh custom visitor/contact properties, use POST /api/widget/set-properties.

{
  "app_id": "proj_123",
  "visitor_id": "user_456",
  "properties": {
    "feature_flag": "beta",
    "last_seen_area": "billing"
  }
}

This route merges into visitor and linked contact metadata. It is useful for product context, but it does not update company metadata.

CRM stage precedence

Widget-facing stage updates accept an optional stage_update_mode field on visitor identify and stage-setting requests.

• advance_only is the default and prevents widget updates from moving a company backward when the CRM already has a later stage
• exact applies the requested stage exactly and should be reserved for authoritative backend syncs

The project default can be configured in Settings → Widget → CRM Stage Sync. Per-request values still override that default when you need different behavior.

What this is not

The current public API key surface under /api/v1 does not yet expose visitor/company metadata write routes. Use the widget-facing identify flow when you need to push end-user contact and company context.

Guidance

Prefer the higher-level REST API and MCP docs first. Drop to this layer when you need deeper visitor-specific integration behavior tied to a customer-facing widget session.