Skip to main content

​
Overview

Add a floating bubble button to your website that opens your assistant in a chat interface. This provides a non-intrusive way for users to access your assistant while maintaining your website’s design. The button appears as a floating element that users can click to open a chat window.

​
Basic Implementation

<invent-assistant assistant-id="YOUR_ASSISTANT_ID" />
<script type="text/javascript" src="https://www.useinvent.com/button.js" async defer></script>

​
Attributes

​
assistant-id (Required)

The unique identifier of your assistant. This is the only required attribute. 
<invent-assistant assistant-id="ast_YOUR_ASSISTANT_ID" />

​
theme-appearance

Controls the theme appearance. Options: auto, light, dark Default: auto 
<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  theme-appearance="dark"
/>

​
theme-button-background-color

Custom background color for the bubble button. Accepts any valid CSS color value (hex, rgb, etc.). 
<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  theme-button-background-color="#6366f1"
/>

​
theme-button-color

Custom text/icon color for the bubble button. Accepts any valid CSS color value (hex, rgb, etc.). 
<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  theme-button-color="#ffffff"
/>

​
User Authentication

Always generate the user-hash on your backend using your assistant’s secret key. Never expose the secret key to the client or generate the hash in frontend code.

​
Understanding User Authentication vs Contact Updates

There are two distinct features for managing user information:
  1. Manual User Authentication (described in this section)
    • Requires both user-id and user-hash to be provided together
    • Used for authenticated sessions with your application users
    • Enables personalized experiences and session management
    • The hash validates the user’s identity securely
  2. Automatic Contact Updates (AI feature)
    • The assistant can automatically update contact information (name, email, phone) when detected in conversations
    • Works independently of authentication
    • No hash required for this feature
    • Available for all sessions, authenticated or anonymous
If you want to pre-authenticate users from your application, follow the instructions below. Otherwise, the assistant will create an anonymous session and can still collect contact information through conversation.

​
Secret Key

Generate a secret key to enable user authentication for your assistant. This key is required to create secure user hashes for authenticated sessions.
  1. Navigate to your assistant settings in the Invent dashboard
  2. Click Generate Secret Key
  3. Store this key securely on your backend server

​
Authentication Parameters

To authenticate users from your application, include these parameters as attributes on the invent-assistant element. This enables personalized experiences, session management, and user-specific analytics. If no user authentication is used, an anonymous session is created.

​
user-hash

Required for authentication. HMAC-SHA256 hash of the user_id using your assistant’s secret_key. This ensures secure authentication and must be generated on your backend.

​
user-id

The unique user identifier from your application. Used for session management, analytics, and maintaining conversation history across sessions.

​
user-name

Display name for the user (full name, first name, username, etc.). Used for personalization in chat messages and Invent Contacts. HTML-encode special characters.

​
user-avatar

URL to the user’s avatar image. Will be displayed in chat messages and Invent Contacts. Must be a publicly accessible HTTPS URL.

​
Authenticated Implementation

​
Frontend Code

<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  user-hash="<?php echo $user_hash; ?>"
  user-id="<?php echo $user_id; ?>"
  user-name="<?php echo htmlspecialchars($user_name); ?>"
  user-avatar="<?php echo htmlspecialchars($user_avatar); ?>"
/>
<script type="text/javascript" src="https://www.useinvent.com/button.js" async defer></script>

​
Backend Hash Generation

<?php
$secret_key = 'your_secret_key_here'; // Store securely in env variables
$user_id = '12345'; // Your user's unique ID
$user_name = 'John Doe';
$user_avatar = 'https://example.com/avatars/john.jpg';

// Generate HMAC-SHA256 hash
$user_hash = hash_hmac('sha256', $user_id, $secret_key);
?>

​
Complete Example

​
Full HTML Page with Authentication

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>

  <!-- Your website content -->

  <!-- Invent Assistant Button -->
  <invent-assistant
    assistant-id="YOUR_ASSISTANT_ID"
    theme-appearance="auto"
    theme-button-background-color="#6366f1"
    theme-button-color="#ffffff"
    user-hash="<?php echo $user_hash; ?>"
    user-id="<?php echo $user_id; ?>"
    user-name="<?php echo htmlspecialchars($user_name); ?>"
    user-avatar="<?php echo htmlspecialchars($user_avatar); ?>"
  />
  <script type="text/javascript" src="https://www.useinvent.com/button.js" async defer></script>
</body>
</html>

​
Customization Examples

​
Dark Theme with Custom Colors

<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  theme-appearance="dark"
  theme-button-background-color="#1f2937"
  theme-button-color="#60a5fa"
/>
<script type="text/javascript" src="https://www.useinvent.com/button.js" async defer></script>

​
Light Theme with Brand Colors

<invent-assistant
  assistant-id="ast_YOUR_ASSISTANT_ID"
  theme-appearance="light"
  theme-button-background-color="#8b5cf6"
  theme-button-color="#ffffff"
/>
<script type="text/javascript" src="https://www.useinvent.com/button.js" async defer></script>

​
Best Practices

Security

Never expose your secret key in client-side code. Always generate hashes on your backend server.

Performance

Use the async defer attributes on the script tag for optimal page load performance.

User Experience

Customize button colors to match your brand for a seamless user experience.

Privacy

Only pass user information when the user is logged in to respect privacy.

​
Troubleshooting

Possible causes:
  • Invalid assistant ID
  • Script not loaded properly
  • JavaScript errors in console
Solutions:
  • Verify your assistant ID is correct
  • Check browser console for errors
  • Ensure the script URL is accessible
Possible causes:
  • Invalid user hash
  • Secret key mismatch
  • User ID format issues
Solutions:
  • Verify hash generation using correct secret key
  • Ensure user ID matches exactly
  • Check that user ID is a string
Possible causes:
  • CSS conflicts
  • Invalid color values
  • Theme appearance not applying
Solutions:
  • Use valid CSS color formats (hex, rgb, rgba)
  • Check for CSS specificity conflicts
  • Verify theme-appearance value