Auto User Identification Introduction

This guide is designed for two roles:

• Admins: Enable and manage identity verification at the organization level

• Developers: Integrate user identity securely into the Kino widget

---

For Admins: Enable & Manage Auto User Identification

What is Auto User Identification

Auto User Identification ensures that user information shown to agents is trustworthy. Verified user profiles help agents better understand who they are talking to and prevent incorrect or tampered data from being stored.

How to Enable

• Go to Setting→ User identify

• Only Admins or Super Admin can manage user identify settings

Auto User Identification Settings

After enabling Auto User Identification, admins must configure the User Identity form to define which user information can be identified and displayed.

In Settings → User identity, admins can:

1. Enable / Disable Auto User Identification

• Turn User identity on or off

When disabled, all incoming user data is treated as invaild, even if signed

2. Require Authentication Before Starting a Chat

Admins can require users to provide User Identity before starting a human support conversation.

When enabled, visitors who have not passed any User Identity field will be prompted to sign in when they try to start a chat or submit a pre-chat form. Opening the Widget does not trigger the authentication dialog.

Admins can customize the Dialog title, Dialog message, Button text, and optional Sign-in URL. If no Sign-in URL is configured, clicking the primary button closes the dialog.

No human support conversation is created or assigned to an agent until User Identity is provided.

3. Configure User Fields

Admins can choose which user fields are recognized and shown to agents:

• Name (built-in)

• Email (built-in)

• User segments (with tier, priority configuration and VIP)

VIP tiers allow high-value customers to be prioritized during agent assignment. When a VIP customer enters a conversation, the system will first attempt to assign the conversation to an available VIP Agent within the matched group. If no VIP Agent is available, the system automatically falls back to normal assignment logic.

Each field includes:

• A Label (display name for agents)

• Optional tier values and priorities (for segmentation fields)

Tier priorities directly affect conversation routing and assignment logic — higher priority tiers will be matched and assigned first.

4. Add Custom Fields

Admins can define additional custom identity fields:

• Field key: Unique identifier used by developers when passing data

• Label: Display name shown to agents

Only fields configured in this form can be:

• Displayed in the agent console

• Marked as Verified / Unverified

If a field is not configured here, data passed from the frontend will be ignored, even if included in a signed token.

（Recommanded）Verified User Identification

Identifying users with a signed token is optional, not mandatory. You can choose to pass user data with or without a signature depending on your trust and security requirements.

Use this option when you already know who the user is (for example, after login). Identity must be created and signed on your server-side.

How to Enable

• Only Super Admins can manage secret keys

• Go to Manage all workspace→ Security → User identification secret key

Secret Key Rules

• Keys can be created, viewed, copied, and deleted

• Up to 5 active secret keys are allowed

• Deleting a key immediately invalidates signatures created with it

• Keys can be applied to all workspace under this orgnization

How to use it

To finish the integration, share the secret key with your developer and follow the steps outlined below.

Quick note: Keep your secret key secure and do not share it publicly.

What Agents Will See

• Verified: User data is authenticated and marked as verified

• Unverified: User data is shown but not verified

• Invalid: User data is not displayed or stored

For Developers: Pass & Verify User Identity

KinoChat supports passing a signed userToken via

• Popup/Full-page mode

• Direct link mode

Installation

This is the example widget installation code for KinoChat. You can got it from: Setting → Installation, follow this article

This is example for popup mode

<script>
  "use strict";
  !(function (n) {
    var w = window, t = (w[n] = w[n] || function () { t.c(arguments); });
    if (t.invoked)
      return void (w.console && console.error(n + " snippet included twice."));
    t.q = [];
    t.invoked = !0;
    t.c = function (e) { t.q.push(e); };
    (function () {
      var s = document.createElement("script");
      s.async = !0;
      s.crossOrigin = "anonymous";
      s.src = "YOUR-WORKSPACE-URL";
      var t = document.getElementsByTagName("script")[0];
      t.parentNode.insertBefore(s, t);
    })();
  })("CustomerSupportWidget");
  
  CustomerSupportWidget("boot", {
    workspaceId: "YOUR-WORKSPACE-ID",
    mode: "popup",
  });
</script>

This is example for Full-page mode

<script>
  "use strict";
  !(function (n) {
    var w = window, t = (w[n] = w[n] || function () { t.c(arguments); });
    if (t.invoked)
      return void (w.console && console.error(n + " snippet included twice."));
    t.q = [];
    t.invoked = !0;
    t.c = function (e) { t.q.push(e); };
    (function () {
      var s = document.createElement("script");
      s.async = !0;
      s.crossOrigin = "anonymous";
      s.src = "YOUR-WORKSPACE-URL";
      var t = document.getElementsByTagName("script")[0];
      t.parentNode.insertBefore(s, t);
    })();
  })("CustomerSupportWidget");
  
  CustomerSupportWidget("boot", {
    workspaceId: "YOUR-WORKSPACE-ID",
    mode: "newPage",
  });
</script>

Direct Link Mode

Copy from Setting → Installation

Adding Auto User Identification (Verified)

1

Step 1: Configure identity fields in Admin Console

Before sending identity data, admins must configure allowed fields in: Settings → User identity

Only configured fields will be accepted and displayed. You can follow this to configure.

2

Step 2: Generate JWT on Your Server-side

When using userToken, Kino requires the JWT payload to follow the exact structure below. The fields included must match the fields configured in Settings → User identity.

{
  sub: "<USER-ID>",      // Required: your unique user ID
  exp: 2114352386,        // Required. The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. Use timestamp in seconds
  updateMode: "merge", // Optional. "merge" or "replace". default: "merge", "merge" updates only the fields you provide and keeps all other existing fields unchanged. "Replace" completely overwrites existing attributes.
  user: {
    // Built-in identity fields (must match Settings → User identity)
    name: "<USER-NAME>",
    email: "<USER-EMAIL>",

    // User segment field (Tier1–Tier20 only，must match Settings → User identity)
    tier: "Tier3",

    // Custom identity fields (keys must match admin configuration)
    custom_field_key_1: "value1",
    custom_field_key_2: "value2"
  }
}

JWTs must be signed with your User identification secret key (HS256).

A JWT must include:

• Header(Fixed): { "alg": "HS256", "typ": "JWT" }

• Payload: sub , exp, and user fields

JWTs must be generated server-side. Never expose your secret key in frontend code.

3

Step 3: Pass userToken in the Boot Call

You just need add one field to the standard popup or fullpage install.

Popup mode

CustomerSupportWidget("boot", {
  workspaceId: "YOUR-WORKSPACE-ID",
  mode: "popup",
  userToken: "<SIGNED-JWT>",
});

fullpage mode

CustomerSupportWidget("boot", {
  workspaceId: "YOUR-WORKSPACE-ID",
  mode: "newPage",
  userToken: "<SIGNED-JWT>",
});

Send Token After Boot

If the visitor logs in after the widget has already been booted, you can attach identity later using setUserToken.

This method ony works for popup mode. Not for fullpage mode.

CustomerSupportWidget("setUserToken", "<SIGNED-JWT>");

4

(Optional) Pass userToken via Direct Link

You may pass a signed token via URL:

https://your-customer-site.com/chat?workspaceId=<WORKSPACE_ID>&userToken=<SIGNED-JWT>

On initialization, we will

1. Detect userToken in URL

2. Validate JWT

3. Bind identity as Verified

4. Remove token from URL (without reload)

5

Step 4: Reset the Widget Session (Required on Logout)

When a user logs out or switches accounts, you must reset the widget session to prevent cross-user identity leakage.

This method ony works for popup mode. Not for fullpage mode.

CustomerSupportWidget("reset");

What reset does

• Ends the active chat (if any)

• Clears stored identity and attributes

• Starts a new anonymous visitor session

6

For Guest Users (No Verification)

This method ony works for popup mode. Not for fullpage mode.

Pass attributes

If you don’t need identity verification, you can still pass attributes:

Pass userToken in the Boot Call

CustomerSupportWidget("boot", {
  workspaceId: "YOUR-WORKSPACE-ID",
  mode: "popup",

  userAttributes: {
    // Built-in identity fields (must match Settings → User identity)
    name: "<USER-NAME>",
    email: "<USER-EMAIL>",

    // User segment field (Tier1–Tier5 only，must match Settings → User identity)
    tier: "Tier3",

    // Custom identity fields (keys must match admin configuration)
    custom_field_key_1: "value1",
    custom_field_key_2: "value2"
  }
});

Send Token After Boot

CustomerSupportWidget("setUserAttributes", {
  // Built-in identity fields (must match Settings → User identity)
  name: "<USER-NAME>",
  email: "<USER-EMAIL>",

  // User segment field (Tier1–Tier5 only，must match Settings → User identity)
  tier: "Tier3",

  // Custom identity fields (keys must match admin configuration)
  custom_field_key_1: "value1",
  custom_field_key_2: "value2",
});

These attributes will be treated as Unverified.

(Optional) Merge vs Replace

Only work for Guest Users

By default, Kino merges attributes if you call setUserAttributes several times

Example (merge mode):

// Current stored attributes:
// { name: "Jane", email: "[e-mail]", tier: "Tier3", region: "EU" }
// Update
CustomerSupportWidget("setUserAttributes", {
  tier: "Tier5",
});

// Result (region is kept):
// { name: "Jane", email: "[e-mail]", tier: "Tier5", region: "EU" }

If you want to replace the attributes, you need to set the mode as replace.

CustomerSupportWidget(
  "setUserAttributes",
  {
    name: "New Name",
  },
  { mode: "replace" },
);

Example (replace mode):

// Current stored attributes:
// { name: "Jane", email: "[e-mail]", tier: "Tier3", region: "EU" }
// Update
CustomerSupportWidget(
  "setUserAttributes",
  {
    name: "Jane",
    tier: "Tier1",
  },
  { mode: "replace" },
);

// Result (email and region are removed):
// { name: "Jane", tier: "Tier1" }