Identifying Visitors

By default, visitors are anonymous. Once you know who they are (for example, after they log in to your app), call Convot.identify() to attach their identity to the current session. This links the chat to their contact record and shows their profile data in your inbox.

The identify call

Call this from your app’s JavaScript after the widget has loaded, typically right after login or page load for authenticated users:

<script>
  // Call this when you know who the visitor is (e.g. after login).
  Convot.identify({
    email: "[email protected]",       // match by email
    external_id: "your_user_id_123",     // or match by your own ID
    name: "Jane Doe",
    company: "Acme Inc",
    phone: "+1234567890",
    avatar_url: "https://example.com/avatars/jane.png",
    user_hash: "SERVER_GENERATED_HMAC",  // see Identity Verification
    custom_data: {                       // any extra key-value pairs
      plan: "pro",
      shopify_store: "my-store.myshopify.com",
      order_count: 42
    }
  });
</script>

How matching works

Convot merges the identify call into an existing contact or creates a new one:

1. If external_id is provided, it looks for an existing contact with that external ID in your organization.
2. If not found by external_id, it tries to match by email.
3. If still no match, a new contact is created.

What gets updated

Every field you pass in Convot.identify() is written to the contact. Fields you omit are left unchanged. custom_data is merged (not replaced), so passing a subset of keys adds or updates those keys without wiping others.

Custom data protection

For security, Convot does not let an unverified identify call overwrite existing custom data with lower-confidence values. If a session doesn’t own the contact (e.g., a different visitor claiming someone else’s email), incoming keys can only fill blanks - they cannot overwrite saved values. This prevents spoofing another user’s data. To allow full writes, use Identity verification.

When to call identify

• On page load for pages that require login (the user is already authenticated when the page loads).
• After login - call it in the success callback of your login flow.
• On plan change or profile update - re-call it to update custom data fields like plan or order_count.

You can call Convot.identify() multiple times in a session. Each call is merged.

Carrying identity to your help center

Convot.identify() only identifies the visitor on the page you call it from. When that same logged-in user opens your help center (a different domain), they arrive anonymous again because the browser treats it as a new site. To keep them identified across that hop, pass a signed token in the link as ?convot_identity=.... Links opened from inside the widget do this automatically. See Widget JavaScript API for Convot.identityToken() and server-side token examples.

Next steps

• Identity verification - sign the call server-side so spoofing is impossible.
• Custom data - what you can store and how it appears in the sidebar.
• Widget JavaScript API - keep users identified in your help center.