Chat Widget

Add AI-powered customer support to any website with a single line of code.

Overview

The InnConnect Chat Widget is a lightweight JavaScript component that you embed on your website. Once installed, it gives your visitors an AI-powered support assistant that draws on your Knowledge Base to answer questions in real time. No server-side integration is required on your end.

The widget connects to the InnConnect platform using a site-scoped API key. All AI processing, session management, knowledge retrieval, and escalation logic runs on InnConnect's infrastructure. Your website simply loads the script.

Installation

Add two script blocks to your website's HTML, just before the closing </body> tag. The first block configures the widget, the second loads it.

<!-- InnConnect Chat Widget -->
<script>
  window.InnConnectConfig = {
    apiUrl: 'https://innconnect.io/api',
    apiKey: 'YOUR_API_KEY_HERE',
    primaryColor: '#E85D04',
    position: 'bottom-right'
  };
</script>
<script src="https://innconnect.io/widget/innconnect-widget.js" defer></script>

That is all that is required. The widget button appears immediately on page load and is ready to accept customer messages.

Finding your API key

1. Log in to the InnConnect admin panel.
2. Navigate to Sites in the sidebar.
3. Select the site you want to connect the widget to.
4. Open the Settings tab. Your API key is displayed at the top of the page.

Configuration

The widget is configured via the window.InnConnectConfig JavaScript object. Set the properties before loading the widget script.

For deeper customization — system prompt, AI model, welcome message, primary color, escalation behavior — configure those settings in the admin panel under Sites → [Your Site] → Settings. Changes take effect immediately without modifying the embed code.

How It Works

Understanding the end-to-end message flow helps you debug issues and optimize your Knowledge Base for accuracy.

Widget lifecycle

1. Script loads — The widget script initializes by reading the window.InnConnectConfig object and fetches display configuration from GET /api/chat/config.
2. Customer opens widget — A new chat session is created via POST /api/chat/session. The session ID is stored in the customer's browser (localStorage), so the conversation persists across page navigations.
3. Customer sends a message — The widget sends the message to POST /api/chat/message with the API key in the X-API-Key header.
4. Server processes the message — Input is sanitized, escalation triggers are checked, a RAG search retrieves relevant KB articles, and the configured AI provider generates a response. The response is sanitized server-side before being returned.
5. Widget renders the response — Markdown is parsed and rendered with DOMPurify sanitization. Typing indicators provide visual feedback while the AI generates.

AI response pipeline

Widget Features

Escalation

When the AI determines it cannot adequately answer a question, or when the customer explicitly asks to speak to a human, the conversation is escalated. Escalated conversations appear in the admin panel under Escalations, where agents can review the full history and take over the chat seamlessly.

Sessions

Every chat interaction is tracked as a session. Sessions are the fundamental unit of conversation in InnConnect.

Session statuses

Conversation Rating

After a conversation ends, customers are invited to rate their experience. Ratings provide quantitative insight into AI performance and Knowledge Base quality.

• Star rating — 1 to 5 stars, where 5 is excellent.
• Tags — Optional predefined tags (e.g. "Helpful", "Too slow", "Wrong answer") for quick categorization.
• Free-text feedback — Optional comment for detailed feedback.

Ratings are visible in the admin panel analytics. Aggregate scores appear on the Dashboard. Low-rated sessions can be filtered in the Escalations panel for review, making it easy to identify KB gaps and improve article quality.

API Reference

The chat widget communicates with InnConnect through a public REST API. All endpoints require the X-API-Key header with your site's API key. These endpoints are also available for custom integrations if you want to build your own chat interface.

Security

The chat widget is a public-facing component running on third-party websites. InnConnect applies multiple layers of protection to ensure safe operation.

Widget Title

The widget automatically fetches its title from the API on startup. Set a custom title per site under Sites → General → Widget Title. No embed snippet update needed — the widget reads the title from the server.

Proactive Suggestions

The widget can show suggestion bubbles above the chat button before the visitor opens the chat. These are configured per page under Sites → Page context.

Suggestions can be triggered by: time elapsed since page load, scroll depth (0–100%), or a CSS element entering the viewport. Multiple triggers can be combined — all must be satisfied.

Visitor Tracking

Each visitor receives a unique visitor ID stored in localStorage. This ID is sent with every API call, allowing InnConnect to track visit history, page frequency, and topic interests across sessions.

Visitor profiles are available in Visitor Insights — showing top pages, interests, session count, and conversion events.