JavaScript Embed Features
Identity Verification
Securely identify end users in your embedded chatbot to enable personalized conversations and contact management.
Overview
Identity Verification allows you to pass authenticated user information to your embedded chatbot. When users are logged into your application, you can share their identity so the AI agent can provide personalized responses, address users by name, and associate conversations with specific contacts.
How It Works
User identity can be passed to the chatbot widget in three ways, depending on your integration method.
Method 1: Script Tag (data attributes)
When using the auto-init script tag, pass user data via data-user-* attributes: <script src="https://cdn.docimal.site/latest/docimal-chatbot.js" data-api-key="dcml_pk_YOUR_API_KEY" data-base-url="https://api.docimal.site/agents" data-user-email="john@example.com" data-user-name="John Doe" data-user-id="user_123" data-user-phone="+1234567890" async ></script> All data-user-* attributes are optional. Include only the ones available from your authentication system.
Method 2: JavaScript SDK (mountChatbot)
When using the JavaScript SDK for more control, pass user data in the user prop: DocimalChatbot.mountChatbot("#my-container", { apiKey: "dcml_pk_YOUR_API_KEY", apiBaseUrl: "https://api.docimal.site/agents", user: { id: "user_123", name: "John Doe", email: "john@example.com", phone: "+1234567890", customAttributes: { plan: "pro" } } }); This method supports all user properties including customAttributes, which is not available via data attributes.
Method 3: iFrame Embed (URL parameters)
When embedding via iframe, pass user data as URL parameters: <iframe src="https://cdn.docimal.site/embed.html?key=dcml_pk_YOUR_API_KEY&userEmail=john@example.com&userName=John+Doe&userId=user_123&userPhone=%2B1234567890" width="400" height="600" style="border: none;" ></iframe> URL-encode special characters (e.g., + becomes %2B). All user parameters are optional.
Supported User Properties
The user object supports the following properties: id (unique identifier), name (display name), email (email address), phone (phone number), and customAttributes (a key-value object for any additional data like subscription plan, account age, etc.). Custom attributes are accessible in workflows through the user variable scope. All properties are optional — pass only what you have available. Note: customAttributes is only supported via the JavaScript SDK (mountChatbot), not via data attributes or iframe URL parameters.
Session Isolation
When user identity is provided, chat sessions are automatically linked to that user. This enables Session History to show only sessions belonging to the authenticated user, even across different devices. Without user identity, sessions are isolated per device using an auto-generated anonymous ID stored in localStorage. See the Session History documentation for more details on visitor isolation behavior.
Security Considerations
Identity verification happens client-side, so never pass sensitive data like passwords or tokens. User data is sent as session metadata to the Docimal API over HTTPS. For additional security, configure Allowed Domains on your API key to restrict which websites can use your chatbot. The API key itself is validated via HMAC and bcrypt on the server side.