User session identity

User Session Verification

User Session Verification ensures secure communication of User/Session ID (user_id) between your server and our AI Actions and the AI Agent by using HMAC-based authentication.

Server-Side Implementation

You'll need to generate an HMAC hash on your server for each logged-in user. Keep your secret key secure and never expose it in client-side code or commit it to version control.

Node.js

const crypto = require('crypto');

const secret = 'YOUR_SECRET_KEY'; // Your verification secret key
const userId = current_user.id // A string UUID to identify your user

const hash = crypto.createHmac('sha256', secret).update(userId).digest('hex');

Python

import hashlib
import hmac

secret = 'YOUR_SECRET_KEY'  # Your verification secret key
user_id = current_user.id  # A string UUID to identify your user

hash_value = hmac.new(
    secret.encode('utf-8'),
    user_id.encode('utf-8'),
    hashlib.sha256
).hexdigest()

PHP

<?php
$secret = 'YOUR_SECRET_KEY'; // Your verification secret key
$userId = $currentUser->id; // A string UUID to identify your user

$hash = hash_hmac('sha256', $userId, $secret);
?>

Ruby

require 'openssl'

secret = 'YOUR_SECRET_KEY' # Your verification secret key
user_id = current_user.id # A string UUID to identify your user

hash = OpenSSL::HMAC.hexdigest('sha256', secret, user_id)

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

String secret = "YOUR_SECRET_KEY"; // Your verification secret key
String userId = currentUser.getId(); // A string UUID to identify your user

try {
    Mac mac = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
    mac.init(secretKeySpec);
    
    byte[] hashBytes = mac.doFinal(userId.getBytes());
    StringBuilder hash = new StringBuilder();
    for (byte b : hashBytes) {
        hash.append(String.format("%02x", b));
    }
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
    e.printStackTrace();
}

Generating Your Secret Key

Before implementing server-side HMAC authentication, you'll need to generate a secret key from your Chatislav dashboard:

1. Navigate to Settings → Deploy in your Chatislav dashboard

2. Click Generate Key to create a new verification secret key

3. Copy the generated key and store it securely in your server environment

Important Security Notes:

• Keep your secret key secure and never expose it in client-side code
• Do not commit your secret key to version control
• Store it as an environment variable on your server
• Regenerate the key if you suspect it has been compromised

Client-Side Implementation

After generating the hash on your server, you need to configure the client-side to pass user identification to your AI Agent for server actions.

Method 1: Using Embed Code Configuration

Add this configuration before the chatislav script loads. The chatislav_user_session_config is an array containing the user session config object and optionally an instance_id.

For a specific widget instance:

<script>
window.chatislav_user_session_config = [
  {
    user_id: "unique-user-identifier",
    user_id_hash: "generated-hash-from-server", // Hash generated on server
    user_metadata: {
      "name": "John Doe",
      "email": "john@chatislav.ai",
      "current_url": "https://chatislav.ai/en/plans",
      "subscription_tier": "premium",
      "last_login": "2025-06-25T10:30:00Z"
      // Add any other relevant user information
    }
  },
  "ctslv_bbl" // instance_id for this configuration
];
</script>

<script>
  (function (w, d, o, f) {
    w[o] =
      w[o] ||
      function (config) {
        var js = d.createElement("script");
        js.src = f;
        js.async = true;
        js.onload = function () {
          var e = d.createElement("div");
          e.id = o;
          d.body.appendChild(e);
          w.init_chatislav
            ? w.init_chatislav(o, config)
            : console.error("chatislav init function not available.");
        };
        d.body.appendChild(js);
      };
  })(window, document, "ctslv_bbl", "https://chatislav.ai/api/static/chat-bot/index.js");
  
  ctslv_bbl({ 
    base_url: "https://chatislav.ai/api", 
    token: "your-widget-token" 
  });
</script>

For all widget instances (global configuration):

<script>
window.chatislav_user_session_config = [
  {
    user_id: "unique-user-identifier",
    user_id_hash: "generated-hash-from-server", // Hash generated on server
    user_metadata: {
      "name": "John Doe",
      "email": "john@chatislav.ai",
      "current_url": "https://chatislav.ai/en/plans",
      "subscription_tier": "premium",
      "last_login": "2025-06-25T10:30:00Z"
      // Add any other relevant user information
    }
  }
  // No instance_id - applies to all widgets
];
</script>

Method 2: Using SDK user_session Method

Load the chatislav script first, then call the user_session method with the specific instance_id:

window.chatislav.user_session({
  user_id: "unique-user-identifier",
  user_id_hash: "generated-hash-from-server", // Hash generated on server
  user_metadata: {
    "name": "John Doe",
    "email": "john@chatislav.ai",
    "current_url": "https://chatislav.ai/en/plans",
    "account_type": "business",
    "preferences": {
      "language": "en",
      "timezone": "UTC-5"
    }
    // Add any other relevant user information
  }
}, "ctslv_bbl"); // instance_id parameter

Method 3: Multiple Widget Instances

If you have multiple chatislav widgets on the same page, you can configure each one separately by setting window.chatislav_user_session_config multiple times:

<script>
// Configuration for first widget instance
window.chatislav_user_session_config = [
  {
    user_id: "unique-user-identifier",
    user_id_hash: "generated-hash-from-server",
    user_metadata: {
      "name": "John Doe",
      "email": "john@chatislav.ai",
      "role": "customer"
    }
  },
  "ctslv_bbl" // First widget instance
];

// Configuration for second widget instance
window.chatislav_user_session_config = [
  {
    user_id: "unique-user-identifier",
    user_id_hash: "generated-hash-from-server",
    user_metadata: {
      "name": "John Doe",
      "email": "john@chatislav.ai",
      "role": "admin"
    }
  },
  "ctslv_support" // Second widget instance
];
</script>

Or using the SDK method:

// Configure first widget
window.chatislav.user_session({
  user_id: "unique-user-identifier",
  user_id_hash: "generated-hash-from-server",
  user_metadata: {
    "name": "John Doe",
    "role": "customer"
  }
}, "ctslv_bbl");

// Configure second widget
window.chatislav.user_session({
  user_id: "unique-user-identifier",
  user_id_hash: "generated-hash-from-server",
  user_metadata: {
    "name": "John Doe",
    "role": "admin"
  }
}, "ctslv_support");

 

Configuration Properties

The user_session method accepts the following properties for server action payload verification:

Property	Type	Required	Description
user_id	String	No	Unique identifier for the user/session (e.g., UUID). When provided with user_id_hash, this is validated using HMAC authentication.
user_id_hash	String	No	HMAC-SHA256 hash of the user ID generated on your server using your secret key. Required when user_id is provided.
user_metadata	Object	No	Additional user information available to the AI Agent as context. Maximum 2000 characters total across all metadata fields.
instance_id	String	No	The widget instance identifier (e.g., "ctslv_bbl"). If not provided, the configuration will apply to all instances.

 

User Metadata Validation Behavior

The AI Agent's access to user metadata depends on whether user authentication is provided:

Without User Authentication (user_id and user_id_hash not provided):

• The AI Agent will always receive the user_metadata in its context
• No validation is performed
• Metadata is immediately available for personalization and context

With User Authentication (user_id and user_id_hash provided):

• The system validates the user_id against the user_id_hash using HMAC authentication
• Only if validation succeeds will the AI Agent receive the user_metadata in its context
• If validation fails, both the user_id and user_metadata are excluded from the AI Agent's context
• This ensures that metadata is only accessible when user identity is properly verified

This dual behavior allows you to:

• Provide anonymous personalization using metadata without authentication
• Ensure secure, verified user context when authentication is required

 

Additional Notes

Mismatched User ID and User Hash

If the user_id and user_id_hash do not match during validation, both the user_id and user_metadata will be removed from all custom actions API requests. The AI Agent will operate without user context in this case.

Calling user_session multiple times

Calling user_session multiple times for the same instance will overwrite the previous properties for that specific instance.

Instance ID

The instance_id parameter corresponds to the widget identifier used in your embed code. In the example above, "ctslv_bbl" is the instance ID. This allows you to have different user session configurations for different widget instances on the same page.

User Metadata

User metadata provides contextual information that your AI Agent can use to deliver personalized responses and make informed decisions during server actions. This metadata acts as additional context that helps the agent understand the user's current situation, preferences, and relevant details.

What can you include in user_metadata?

• User profile information (name, email, role)
• Current application state (page URL, active features)
• Business context (subscription level, company info)
• Behavioral data (preferences, recent activity)
• Any other relevant information up to 2000 characters total

How does the AI Agent use this information? The AI Agent can reference this metadata to provide more relevant responses, make better decisions in server actions, and personalize the user experience based on their specific context.

E-commerce Context:

user_metadata: {
  "name": "Sarah Johnson",
  "email": "sarah@example.com",
  "membership_level": "gold",
  "recent_orders": "3",
  "preferred_categories": "electronics,books",
  "current_cart_value": "125.99",
  "current_url": "/checkout"
}

Use case: The AI can provide VIP support for gold members, suggest related products from preferred categories, or offer cart abandonment assistance.

SaaS Application Context:

user_metadata: {
  "name": "Alex Chen",
  "email": "alex@company.com",
  "plan": "enterprise",
  "role": "admin",
  "company": "Tech Solutions Inc",
  "current_url": "/dashboard/analytics",
  "feature_flags": "advanced_reporting,api_access",
  "team_size": "25"
}

Use case: The AI can provide admin-level support, reference enterprise features, suggest team management tools, or offer advanced analytics guidance.

Support Context:

user_metadata: {
  "name": "Maria Rodriguez",
  "email": "maria@example.com",
  "account_status": "active",
  "support_tier": "priority",
  "previous_tickets": "2",
  "current_issue_category": "billing",
  "subscription_expires": "2025-12-31"
}

Use case: The AI can prioritize the user's support request, reference previous ticket history, provide billing-specific assistance, or proactively address subscription concerns.