Identity Verification

What is Identity Verification?

By default, widget visitors are anonymous — identified only by a random UUID stored in the browser. Identity verification lets you cryptographically link a visitor to a real user in your system. When a logged-in user on your site interacts with the widget, you pass their user ID and an HMAC hash to the widget, and our API verifies it server-side. This gives you:

• Persistent identity — the same user is recognized across browsers, devices, and sessions.
• Conversation continuity — if an anonymous visitor starts chatting, then logs in, their conversation history merges automatically.
• Anti-impersonation — user identity is verified with HMAC-SHA256, so it cannot be forged from the browser.
• Richer visitor profiles — verified email, name, and user ID are stored alongside all device and behavior data.

How It Works

The flow has three parts: your backend computes a hash, your frontend passes it to the widget, and our API verifies it.

1. Go to Dashboard → Agent Settings → Install and enable Identity Verification. An identity secret is generated — copy it to your server environment variables. This secret is only shown once.
2. On your backend, after the user logs in, compute HMAC-SHA256(identity_secret, user_id) and pass the resulting hex string to your frontend.
3. On your frontend, call window.NextCap('identify', { ... }) with the user data and the HMAC hash.
4. The widget sends the hash to our API. We verify it against the stored secret. If valid, the visitor is marked as verified.

Step 1 — Server-Side HMAC

Compute the HMAC on your server, never in the browser. The identity secret must stay server-side — treat it like a database password.

const crypto = require('crypto');

// Your identity secret — from Dashboard → Agent Settings → Install
const IDENTITY_SECRET = process.env.NEXTCAP_IDENTITY_SECRET;

// Compute HMAC on your server after the user logs in
const userHash = crypto
  .createHmac('sha256', IDENTITY_SECRET)
  .update(user.id.toString())
  .digest('hex');

// Pass userHash to your frontend template / API response

Step 2 — Client-Side Identify Call

Once you have the HMAC from your server, pass it to the widget using the window.NextCap API. This call can happen at any time — on page load, after login, or when user data becomes available.

<script>
  window.NextCap('identify', {
    userId: 'usr_abc123',         // Required — your internal user ID
    email: 'jane@acme.com',       // Optional — shown in dashboard
    name: 'Jane Doe',             // Optional — shown in dashboard
    userHash: 'a1b2c3d4e5f6...',  // Required — HMAC from your server
    customAttributes: {           // Optional — visible to agents
      plan: 'enterprise',
      role: 'admin',
      company: 'Acme Inc.',
    },
  });
</script>

The window.NextCap function uses a command queue, so you can call it before or after the widget script loads — commands are buffered and executed once the widget is ready.

Parameters

Session Merging

When a visitor starts chatting anonymously and later identifies (e.g., they log in), the widget automatically merges the anonymous session into the verified identity. All conversations, messages, tickets, and activity from the anonymous session are re-parented to the verified visitor. The visitor sees one continuous conversation history.

If the same verified user returns from a different browser or device, they are recognized immediately — no merge needed, their full history is already linked to their verified user ID.

Resetting Identity

When a user logs out, call window.NextCap('reset') to clear the stored identity from the browser. The next visitor interaction will create a new anonymous session.

// When the user logs out of your app
window.NextCap('reset');

Security Notes

• The HMAC comparison uses constant-time comparison (timing-safe) to prevent timing attacks.
• Your identity secret is encrypted at rest using AES-256-GCM. It is only shown once at generation time.
• Regenerating a secret immediately invalidates all existing HMAC hashes — your customers will need to update their server-side code with the new secret.
• Identity verification is additive, not blocking. Anonymous visitors can still use the widget — they just won't have a verified identity.