Identity Verification

Identity Verification

Overview

Nexvio.ai chatbots can be configured to verify the identity of your users. This is done by hashing the user’s ID with a secret key generated by Nexvio.ai. The hashed value is then sent to us with custom action requests and is used to verify the user’s identity. If the user and the hash do not match, the user ID will be removed from all custom action requests. You can also send additional metadata to the chatbot that can be used to personalize the chatbot experience.

Obtaining the User Hash

• The secret key is generated by Nexvio.ai and is used to hash the user’s ID. The secret key is available in the Nexvio.ai dashboard under chatbot Connect > Embed > Embed code with identity.
• Use the secret key to generate the user hash on the server.

const crypto = require("crypto");

const secret = "•••••••••"; // 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");

• Send the user hash and optional metadata to Nexvio.ai with the identify method.

How to Enable Identity Verification

There are two ways to enable identity verification:

1. Using the embed code:

Add this before the Nexvio.ai script.

<script>
window.nexvioUserConfig = {
    user_id: <USER_ID>,
    user_hash: <USER_HASH>, // this is the hash of the user_id, should be generated on the server
    user_metadata: {
        "name": "John Doe",
        "email": "john@example.com",
        "company": "Acme Inc",
        // Add any other relevant user information
    }
}
</script>

Here is an example of what the code should look like when added before the Nexvio.ai script.

2. Using the SDK identify method:

Load the Nexvio.ai script and call the identify method with the user’s properties and optional metadata.

window.nexvio("identify", {
  user_id: "1234567890",
  user_hash: "1234567890", // this is the hash of the user_id, should be generated on the server
  user_metadata: {
    "name": "John Doe",
    "email": "john@example.com",
    "company": "Acme Inc",
    // Add any other relevant user information
  }
});

Allowed Properties

The identify method allows the following properties:

Property	Description
user_id	The ID of the user, the only verified variable as it is verified using the user_hash.
user_hash	The hash of the user’s ID.
user_metadata	Optional object containing additional user information. This can include properties like name, email, company, or any other relevant data that you want to make available to your AI agent. Maximum 1000 characters total for all metadata fields combined. Exceeding this limit will result in the metadata being truncated. It’s strictly used as context to the AI Agent (equivalent to a user message)

Mismatched User ID and User Hash

If the user ID and user hash do not match, the user ID will be removed from all custom actions API requests.

Calling identify multiple times

Calling identify multiple times will overwrite the previous properties.

Security Considerations

• Never expose your secret key in client-side code. The hash should always be generated on your server.
• Implement proper authorization checks on your server to ensure only authorized users can obtain a valid hash.
• Consider adding an expiration mechanism to your hash generation to limit the validity period of the hash.

Example Implementation with Node.js

Here’s an example of how you might implement user identity verification in a Node.js application:

// Server-side code (Node.js)
const express = require('express');
const crypto = require('crypto');
const app = express();

// Your secret key from Nexvio.ai dashboard
const SECRET_KEY = 'your_secret_key_here';

// Endpoint to generate user hash
app.get('/api/get-user-hash', authenticateUser, (req, res) => {
  const userId = req.user.id; // Get the authenticated user's ID

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

  // Return user ID and hash to the client
  res.json({
    userId: userId,
    userHash: hash
  });
});

// Middleware to authenticate user
function authenticateUser(req, res, next) {
  // Your authentication logic here
  // ...

  // If authentication fails:
  // return res.status(401).json({ error: 'Unauthorized' });

  // If authentication succeeds, attach user to request
  req.user = { id: 'user123', name: 'John Doe' };
  next();
}

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Then in your client-side code:

// Client-side code
fetch('/api/get-user-hash')
  .then(response => response.json())
  .then(data => {
    // Initialize Nexvio.ai with user identity
    window.nexvioUserConfig = {
      user_id: data.userId,
      user_hash: data.userHash,
      user_metadata: {
        name: "John Doe",
        email: "john@example.com"
      }
    };

    // Load Nexvio.ai script
    const script = document.createElement('script');
    script.src = 'https://nexvio.ai/embed.js';
    document.head.appendChild(script);
  })
  .catch(error => {
    console.error('Error fetching user hash:', error);

    // Load Nexvio.ai script without identity verification
    const script = document.createElement('script');
    script.src = 'https://nexvio.ai/embed.js';
    document.head.appendChild(script);
  });

This implementation ensures that the secret key never leaves your server, and the hash is generated securely server-side.