Developer Documentation

Everything you need to integrate FlowChat into your web application in under 5 minutes.

1. Getting Started

FlowChat is designed to be completely plug-and-play. Before integrating the widget into your frontend, you need to create an administrator account and generate your unique API key.

Creating an Admin Account

Navigate to the FlowChat Admin Console.
Click on Register and fill in your Company Name, Admin Name, Email, and a secure password.
Once registered, log in with your new credentials.
On the dashboard, locate the Copy API Key button at the top right. Copy this key—you will need it for the integration script below.

2. Frontend Integration

To embed the FlowChat widget into your website, simply copy and paste the following HTML snippet right before the closing </body> tag of your application.

HTML

<!-- FlowChat SDK Embed Code -->
<script 
  src="https://still-hat-aa5c.jehankalutota.workers.dev/widget.js" 
  data-api-key="YOUR_API_KEY_HERE"
  data-position="bottom-right">
</script>

Replace YOUR_API_KEY_HERE with the API key you copied from the Admin Console.

3. Cross-Device Chat Persistence (Crucial)

By default, FlowChat operates in Guest Mode. It assigns a random ID to the visitor and saves it in their browser's local storage. If that visitor clears their browser cache or switches from their phone to their laptop, their chat history will be lost and they will appear as a completely new user to your agents.

To fix this, if your website has a login system (like a SaaS dashboard or an e-commerce store), you should pass the logged-in user's actual database ID into the script dynamically.

<script 
  src="..." 
  data-api-key="..."
  data-user-id="user_89234892"      <-- Dynamically inject from your backend
  data-user-name="Alex Carter"      <-- Optional
  data-user-email="alex@company.com" <-- Optional
></script>

When you provide a data-user-id, FlowChat guarantees that no matter what device or browser the user logs into, their entire conversation history will be pulled from our secure cloud and instantly restored to their screen.

4. FlowChat Features & Architecture

FlowChat is built with modern, enterprise-grade architecture under the hood:

Lazy WebSocket Initialization: The widget boots up in a completely "disconnected" standby state to save network resources. It only establishes the heavy WebSocket connection when the user sends their very first message.
Real-Time STOMP over WebSockets: Ensures instant, bi-directional message delivery with zero polling or refresh latency.
Optimistic UI Rendering: Messages appear on the screen the millisecond you hit "Send", providing a buttery-smooth, native app feel.
Web Audio API Notifications: Admin dashboards emit synthesized, non-intrusive audio "dings" when new messages arrive from customers, utilizing browser audio APIs without needing to download external MP3 assets.
Mobile Optimized: Strict viewport controls and layout constraints prevent iOS auto-zoom bugs and horizontal scrolling overflows.
Tenant-Isolated Security: Every message and conversation is cryptographically isolated by your API key and Tenant ID, ensuring data privacy across different businesses.