Customer Identification and Tracking

Customer Identification and Tracking

Customer identification connects anonymous widget visitors to known customer profiles, enabling personalized support and conversation history across sessions.

How Identification Works

When a visitor first uses the chat widget, Helpium creates an anonymous customer record. Once you identify them (usually after they log in to your app), their anonymous conversations are linked to their known profile.

Identifying Customers via JavaScript

After your user logs in, call Helpium.identify():

Helpium.identify({
    email: 'jane@example.com',
    name: 'Jane Smith',
    id: 'user_123',
    metadata: {
        plan: 'Pro',
        company: 'Acme Corp',
    }
});

The email field is the unique identifier. If a customer with that email already exists, their profile is updated. Otherwise, a new customer is created.

Identifying via API

You can also identify customers server-side:

POST /api/customer/tracking/identify
X-API-Key: your_widget_key

{
    "email": "jane@example.com",
    "name": "Jane Smith",
    "id": "user_123",
    "widget_token": "conversation_widget_token",
    "metadata": { "plan": "Pro" }
}

The widget_token is optional — if provided, it links the specified conversation to the identified customer.

Bearer Token Authentication

For AI Actions that call your API on behalf of the customer, pass a bearer token during identification:

// In your app, create a Sanctum token for the user
const token = await createSanctumToken();

Helpium.identify({
    email: user.email,
    name: user.name,
    bearerToken: token,
});

The bearer token is stored on the customer record and used by AI Actions configured with Customer Bearer authentication. This allows the AI chatbot to make authenticated API calls to your application.

What Agents See

When a customer is identified, agents see their profile in the conversation sidebar:

• Name and email
• Avatar (if provided via avatarUrl)
• External ID (your internal user ID)
• Custom metadata (plan, company, role, etc.)
• Conversation history across all sessions
• Last seen timestamp

Session Continuity

Identified customers can resume previous conversations. When they return to your site and are re-identified, they see their conversation history in the widget.

Best Practices

• Call identify() as soon as the user is authenticated — don't wait for them to open the widget
• Always include email — it's the primary identifier
• Use metadata for information agents need (plan, company, role)
• Rotate bearer tokens periodically for security
• Use the id field to link back to your internal user records