Docs / Chatbot Widget

Chatbot Widget

Deploy an AI chat assistant on any website that answers questions from your document collections. One embed snippet, no coding required.

How It Works

  1. You create a widget in aqoon and link it to an API key
  2. The API key controls which collections the chatbot can search
  3. You paste a <script> tag on your website
  4. Visitors ask questions → aqoon searches your documents → Claude generates an answer
Architecture

The chat UI runs inside an iframe from aqoon's domain. All API calls are same-origin — no CORS configuration needed on your site.

Creating a Widget

  1. Click Chatbot in the sidebar
  2. Click New Widget
  3. Enter a name (shown in the chat header, e.g. "Support Bot")
  4. Select an API key — this determines which collections the chatbot can search
  5. Optionally set allowed domains (one per line) to restrict where the widget can be embedded
  6. Click Save
API Key Scoping

Use a scoped API key (not full-access) if you want the chatbot to search only specific collections. Create the key in API Keys first, then select it when creating the widget.

Embedding on Your Website

After creating a widget, copy the embed snippet from the widget detail page and paste it before the closing </body> tag: 

<script src="https://aqoon.ai/widget/wgt_abc123def456.js"></script>

A chat bubble appears in the corner of your page. Clicking it opens the chat window.

Configuration

Edit your widget to customize its appearance and behavior:

Appearance

Setting Description
Theme color Header and button accent color
Theme mode Light or dark
Widget size Standard or compact
Position Bottom-right or bottom-left
Avatar URL Bot avatar image in the header
Subtitle Text below the title in the header

Behavior

Setting Description
Welcome message First message shown when the chat opens
Suggestions Clickable prompt buttons (one per line)
Input placeholder Placeholder text in the message input
Auto-open Widget opens automatically on page load
Fallback contact Contact info the bot suggests when it can't answer
Custom instructions Additional prompt instructions (e.g. "Always answer in French")

Lead Capture

Enable Require lead capture in widget settings. Visitors must enter their name and contact info before chatting. This data appears in the conversation list in your dashboard.

Viewing Conversations

  1. Go to Chatbot → click your widget
  2. The Conversations table shows all chat sessions
  3. Click a conversation to view the full transcript with rendered markdown

Each session shows: visitor name, message count, status (active/closed), star rating, and timestamps.

Rating & Close

Users can close a conversation by:

  • Typing a closing word (merci, thank you, bye, au revoir, etc.) — the rating overlay appears automatically after the response
  • Clicking the × button in the chat header

The rating overlay asks for 1–5 stars and optional text feedback.

Limits & Cost Control

Setting Default Description
Daily message limit 100 Max messages per day across all visitors
Monthly message limit 3,000 Max messages per month
Max tokens per response 1,024 Controls response length and LLM cost
Context chunks 5 Search results fed to the AI per question
Conversation retention 30 days How long messages are stored (0 = don't store)

When daily or monthly limits are exceeded, the widget automatically pauses and shows "This assistant is currently unavailable." You can resume it manually from the dashboard.

Security

  • Domain locking — Only allowed domains can embed the widget. Requests from other origins are rejected.
  • Rate limiting — 5 messages per minute and 50 per day per IP address, in addition to widget-level budget limits.
  • Turnstile CAPTCHA — Optional Cloudflare Turnstile integration for bot protection. Add your site key in widget settings.
  • Honeypot — Hidden form field that catches automated bots.
  • Prompt injection protection — User messages are sandboxed separately from the system prompt. Document context uses XML delimiters.
  • Output sanitization — AI responses are cleaned before rendering to prevent XSS.
  • IP anonymization — Visitor IP addresses are automatically anonymized after 7 days.

File Upload

When a widget is linked to an agent with Code Interpreter enabled, visitors can attach files to their messages. This lets the agent read and analyse uploaded documents directly in the conversation.

Supported formats: PDF and DOCX. Maximum file size: 20 MB per file.

A paperclip button appears in the message input bar when file upload is available. The visitor clicks it to choose a file, waits for the upload to complete, then sends their message. The agent receives both the message and the file.

Requires Code Interpreter

File upload is only available when the widget is linked to an Active agent with the Code Interpreter tool enabled. It does not appear on standard RAG-only widgets.

To enable file upload: open the agent linked to your widget, enable Code Interpreter in the Tools section, and re-publish the agent.