Integrations

Engaging Visitors: Deploying Your AI Agent on Your Website

Deploy your AI agent directly on your website to provide instant support, answer questions, and engage visitors—all with a customizable, always-available chat experience.

Connect your Agent to your Website’s Chat Widget

Quick Start (2 Minutes)

Add these two elements to your website, just before the closing </body> tag:

1<!-- Step 1: Configure your widget -->
2<script>
3  window.__CHAT_WIDGET_CONFIG = {
4    agentId: "YOUR_AGENT_ID_HERE",
5    widgetButtonImageUrl: "https://your-site.com/path/to/avatar.jpg",
6  };
7</script>
8
9<!-- Step 2: Load the widget -->
10<script src="https://widget-cdn.flockx.io/flockx-chat.min.js" async></script>

That’s it! A chat bubble will appear in the bottom-right corner of your website.

Configuration Options

PropertyTypeRequiredDescription
agentIdstring (UUID)✅ YesYour Flockx agent’s unique identifier
widgetButtonImageUrlstring (URL)❌ NoCustom avatar image for the chat button

Step 1: Access Your Agent Settings

  1. Log in to your Flockx dashboard at flockx.io.
  2. Select the specific agent you want to integrate with your website.
  3. Click on the Settings tab in the agent management panel.

Step 2: Locate the Chat Widget Section

  1. Scroll down to find the Chat Widget section.
  2. This section handles all website-based deployment options.

Step 3: Upgrade to Enterprise (If Needed)

If you haven’t yet subscribed to the Enterprise plan:

  1. Click Upgrade to Enterprise within the Chat Widget section.
  2. You’ll be taken to the package selection screen.
  3. Select a plan and proceed to the Stripe payment page.
  4. Complete your billing information and submit.
  5. You’ll be automatically redirected to your settings dashboard upon completion.

Step 4: Configure Your Widget

Once upgraded:

  1. Enable the Chat Widget via toggle.
  2. Click Configure to:
    • Customize widget appearance (color, size, placement)
    • Set behavior rules (when to open, how it greets)
    • Craft a custom welcome message
  3. A Flockx representative will assist you with setup and design preferences.

Step 5: Add the Widget to Your Website

Finding Your Agent ID

  1. In your Flockx dashboard, navigate to Agents
  2. Click on your agent
  3. Copy the Agent ID from the agent settings or URL (UUID format like f4393fac-1e23-4549-85fe-cd5b6cafff39)

Framework-Specific Examples

In your root layout (src/app/layout.tsx):

1import Script from 'next/script';
2
3export default function RootLayout({ children }) {
4  return (
5    <html lang="en">
6      <body>
7        {children}
8        
9        {/* Flockx Chat Widget Configuration */}
10        <Script id="flockx-chat-config" strategy="beforeInteractive">
11          {`
12            window.__CHAT_WIDGET_CONFIG = {
13              agentId: "YOUR_AGENT_ID_HERE",
14              widgetButtonImageUrl: "/images/your-avatar.jpg",
15            };
16          `}
17        </Script>
18        
19        {/* Flockx Chat Widget Script */}
20        <Script 
21          src="https://widget-cdn.flockx.io/flockx-chat.min.js"
22          strategy="lazyOnload"
23        />
24      </body>
25    </html>
26  );
27}

Best Practices

Avatar Image Recommendations

  • Format: Use .webp for best performance, or .jpg/.png
  • Size: Recommended 80x80px to 200x200px
  • Shape: The widget displays it as a circle, so center your subject
  • Hosting: Use your own domain or a CDN for reliability

Performance Optimization

The widget script loads asynchronously and won’t block your page rendering. For additional optimization, you can delay loading until user interaction:

1// Load only after user interaction (click, scroll, etc.)
2document.addEventListener('scroll', function loadWidget() {
3  window.__CHAT_WIDGET_CONFIG = {
4    agentId: "YOUR_AGENT_ID_HERE",
5  };
6  
7  const script = document.createElement('script');
8  script.src = 'https://widget-cdn.flockx.io/flockx-chat.min.js';
9  document.body.appendChild(script);
10  
11  // Remove listener after first trigger
12  document.removeEventListener('scroll', loadWidget);
13}, { once: true });

Agent Preparation

Before embedding, ensure your agent is configured with:

  • ✅ Clear personality and response style
  • ✅ Relevant knowledge base documents
  • ✅ Welcome message for first-time visitors
  • ✅ Appropriate response length settings

Troubleshooting Tips

  • Widget not appearing? Check browser console for JavaScript errors. Verify your agent ID is correct (UUID format).
  • Enterprise not activated? Ensure payment completed successfully and refresh your settings page.
  • Widget appears but no responses? Test your agent in the Flockx dashboard first. Ensure it’s active and not paused.
  • Customization changes not visible? Clear your browser cache or test in incognito mode.
  • Need hands-on help? Reach out to your assigned rep or contact contact@flockx.io

Security Considerations

  • The widget uses secure WebSocket connections (wss://)
  • Agent ID is public (visible in page source)—this is expected and safe
  • API authentication happens server-side via Flockx infrastructure
  • No sensitive credentials should be placed in client-side code

Benefits of Website Integration

  • Provide real-time AI-powered support to your website visitors
  • Answer frequently asked questions instantly
  • Guide users through your products or services
  • Collect initial information before human handoff (if needed)
  • Operate 24/7 without staffing concerns