Identify logged-in users

Use Knoku.identify() to attach your authenticated user to widget sessions.

By default, widget sessions are anonymous and use an opaque web_id cookie to recognize a returning browser.

Basic usage


window.Knoku?.identify({
  id: 'user_123',
  email: 'user@example.com',
  metadata: {
    plan: 'pro',
    company: 'Acme Inc',
  },
})

All fields are optional. Use the stable user ID from your own system when possible.

Clear identity on logout:


window.Knoku?.identify(null)

Identity is kept in memory. Call identify() again on each page load after your auth state is known.

When to call it

Call identify():

After auth state resolves on initial load
After login, before the user opens the widget
After logout, with null

Wait for the CDN runtime

The CDN script loads asynchronously. Guard against window.Knoku not being ready yet:


function whenKnokuReady(callback, timeoutMs = 10000) {
  if (window.Knoku) {
    callback()
    return
  }
 
  const start = Date.now()
  const timer = setInterval(() => {
    if (window.Knoku) {
      clearInterval(timer)
      callback()
    } else if (Date.now() - start > timeoutMs) {
      clearInterval(timer)
    }
  }, 50)
}
 
whenKnokuReady(() => {
  window.Knoku.identify({
    id: currentUser.id,
    email: currentUser.email,
    metadata: { plan: currentUser.plan },
  })
})

When you use the npm package, await initKnokuWidget(options) resolves after the runtime API is ready.

What is sent

Chat requests include the anonymous web_id and any identity you set:


{
  "user": {
    "web_id": "f1c9463d7e36c5990c5434ce4cfa4011",
    "id": "user_123",
    "email": "user@example.com",
    "metadata": { "plan": "pro" }
  }
}

web_id is always present. id, email, and metadata appear only after identify().

Privacy notes

Identity is sent over HTTPS with widget chat requests.
Knoku stores identity on the session for analytics and review.
identify(null) affects future requests; it does not delete previous sessions.
Keep metadata small and non-sensitive.