Widget Quick Start

Get your chat widget up and running in under 5 minutes with this step-by-step guide.

Step 1: Prepare Your Agent

Before embedding, ensure your agent is configured correctly:

1. Navigate to your agent edit page: /gnosaris/{id}/edit
2. Go to the Publication section
3. Set Access Level to Public or Password Protected
4. Note your agent's Identifier (shown in the URL or publication section)
5. Click Save

WARNING

Private agents cannot be embedded. You must set access to Public or Password Protected.

Step 2: Add the Embed Code

Add this code to your website's HTML, right before the closing </body> tag:

<!-- Configure the widget -->
<script>
  window.gnosariConfig = {
    agentId: 'your-agent-identifier',  // Replace with your agent identifier
    apiUrl: 'https://your-domain.com'   // Replace with your Gnosari domain
  };
</script>

<!-- Load the widget script -->
<script src="https://your-domain.com/gnosari-chat-widget-advanced.js"></script>

Replace these values:

• your-agent-identifier: Your agent's identifier (e.g., support-bot)
• your-domain.com: Your Gnosari instance URL (e.g., chat.yourcompany.com)

Step 3: Test It!

1. Reload your webpage
2. You should see a floating chat button in the bottom-right corner
3. Click the button to open the chat
4. Send a test message

That's it! Your chat widget is now live.

Next: Customize Your Widget

Change Position

Move the button to a different corner:

window.gnosariConfig = {
  agentId: 'your-agent-identifier',
  apiUrl: 'https://your-domain.com',
  position: 'bottom-left'  // Options: bottom-right, bottom-left, top-right, top-left
};

Change Colors

Match your brand:

window.gnosariConfig = {
  agentId: 'your-agent-identifier',
  apiUrl: 'https://your-domain.com',
  primaryColor: '#10b981'  // Your brand color (hex format)
};

Auto-Open on Page Load

Open the chat automatically:

window.gnosariConfig = {
  agentId: 'your-agent-identifier',
  apiUrl: 'https://your-domain.com',
  autoOpen: true
};

Dark Mode

Force dark theme:

window.gnosariConfig = {
  agentId: 'your-agent-identifier',
  apiUrl: 'https://your-domain.com',
  theme: 'dark'  // Options: light, dark, auto
};

Common Use Cases

Customer Support

<script>
  window.gnosariConfig = {
    agentId: 'support-bot',
    apiUrl: 'https://chat.yourcompany.com',
    displayMode: 'bubble',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  };
</script>
<script src="https://chat.yourcompany.com/gnosari-chat-widget-advanced.js"></script>

Sales Assistant (Proactive)

<script>
  window.gnosariConfig = {
    agentId: 'sales-bot',
    apiUrl: 'https://chat.yourcompany.com',
    displayMode: 'sidebar',
    autoOpen: true,
    showAfterSeconds: 3,  // Wait 3 seconds before showing
    primaryColor: '#10b981'
  };
</script>
<script src="https://chat.yourcompany.com/gnosari-chat-widget-advanced.js"></script>

Help Documentation

<script>
  window.gnosariConfig = {
    agentId: 'docs-helper',
    apiUrl: 'https://chat.yourcompany.com',
    displayMode: 'drawer',
    drawerHeight: '50vh',
    primaryColor: '#8b5cf6'
  };
</script>
<script src="https://chat.yourcompany.com/gnosari-chat-widget-advanced.js"></script>

Using the Widget Configurator (Recommended)

The easiest way to generate embed code:

1. Navigate to /gnosaris/{id}/widget in the Gnosari UI
2. Use the visual configurator to customize:
   • Display mode (bubble, sidebar, drawer)
   • Position and size
   • Colors and theme
   • Behavior options
3. Preview changes in real-time
4. Click Copy Embed Code
5. Paste the code into your website

This ensures all configuration is correct and gives you a live preview.

Troubleshooting

Widget Not Showing

Check 1: Agent Access Level

Ensure your agent is set to Public or Password Protected:

/gnosaris/{id}/edit → Publication → Access Level

Check 2: Correct Identifier

Use the agent's identifier (string), not the numeric ID:

// ✅ Correct
agentId: 'support-bot'

// ❌ Wrong
agentId: 123

Check 3: Browser Console

Open browser DevTools (F12) and check the Console tab for errors.

Widget Shows But Won't Connect

Password Required

If your agent is password-protected, add the password to config:

window.gnosariConfig = {
  agentId: 'support-bot',
  apiUrl: 'https://your-domain.com',
  password: 'your-password'  // Skips password prompt
};

CORS Issues

Verify your domain is allowed to embed. Check browser console for CORS errors.

Widget Appears Behind Other Elements

The widget uses high z-index by default. If it's still behind other elements, check for elements on your page with very high z-index values.

Complete Example

Here's a complete HTML page with the widget:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website with Gnosari Chat</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 800px;
      margin: 0 auto;
      padding: 2rem;
    }
    h1 { color: #1f2937; }
    p { color: #6b7280; line-height: 1.6; }
  </style>
</head>
<body>
  <h1>Welcome to My Website</h1>
  <p>Click the chat button in the bottom-right corner to get help!</p>

  <!-- Gnosari Chat Widget -->
  <script>
    window.gnosariConfig = {
      agentId: 'support-bot',
      apiUrl: 'https://chat.yourcompany.com',
      primaryColor: '#6366f1',
      position: 'bottom-right',
      theme: 'auto'
    };
  </script>
  <script src="https://chat.yourcompany.com/gnosari-chat-widget-advanced.js"></script>
</body>
</html>

Advanced Usage

Control the Widget Programmatically

After the widget loads, you can control it with JavaScript:

<script>
  window.addEventListener('gnosari-chat-ready', function() {
    // Widget is ready

    // Open on button click
    document.getElementById('help-button').addEventListener('click', function() {
      window.GnosariChatAdvanced.open();
    });

    // Send a message programmatically
    function sendToSupport() {
      window.GnosariChatAdvanced.open();
      window.GnosariChatAdvanced.sendMessage('I need help with my account');
    }
  });
</script>

<button id="help-button">Get Help</button>
<button onclick="sendToSupport()">Contact Support</button>

Track Widget Events

Monitor widget usage:

<script>
  window.addEventListener('gnosari-chat-open', function() {
    console.log('User opened chat');
    // Track in analytics
    gtag('event', 'chat_opened');
  });

  window.addEventListener('gnosari-chat-new-message', function(e) {
    console.log('New message received:', e.detail);
    // Track message count
  });
</script>

Load Widget Conditionally

Only load the widget on specific pages:

<script>
  // Only load on pricing and contact pages
  if (window.location.pathname.includes('/pricing') ||
      window.location.pathname.includes('/contact')) {

    window.gnosariConfig = {
      agentId: 'sales-bot',
      apiUrl: 'https://chat.yourcompany.com',
      autoOpen: true
    };

    const script = document.createElement('script');
    script.src = 'https://chat.yourcompany.com/gnosari-chat-widget-advanced.js';
    document.body.appendChild(script);
  }
</script>

Next Steps

Now that your widget is working:

1. Customize Further: See Widget Embedding for all configuration options
2. Understand Architecture: Read Embed Architecture for technical details
3. Train Your Agent: Add knowledge and configure traits for better responses
4. Monitor Performance: Review chat sessions and analytics

Tips for Success

✅ DO:

• Test with a public agent first before password-protecting
• Use the widget configurator for visual customization
• Test on mobile devices to ensure responsive behavior
• Monitor chat sessions to improve agent responses

❌ DON'T:

• Don't hardcode passwords in public websites (security risk)
• Don't use numeric IDs for agentId (use string identifier)
• Don't auto-open aggressively (can annoy users)
• Don't forget to test on different browsers and devices

Getting Help

Need assistance?

• Documentation: Widget Embedding Guide
• Architecture: Technical Details
• Support: Contact support via your Gnosari dashboard

---

Ready to embed? Use the Widget Configurator for the easiest setup experience!