Chat Widget #

The Chat Widget is a fully customizable, embeddable AI chat interface that you can add to your website with a single line of code.

Overview #

The Chat Widget allows your website visitors to:

• Ask questions and get instant AI-powered responses
• Access your knowledge base without leaving your site
• See relevant source documents for answers
• Maintain conversation history within a session

Features #

• Zero Configuration: Works out of the box
• Fully Customizable: Colors, fonts, greeting messages, and more
• Responsive Design: Works seamlessly on mobile and desktop
• Streaming Responses: Real-time answer generation with SSE
• Source Attribution: Shows relevant documents used to answer questions
• Session Management: Maintains conversation history per user session
• Rate Limiting: Built-in usage limits to prevent abuse

Authentication #

All widget endpoints require authentication. You can use any of these methods:

API Key (Query Parameter):

?api_key=<your_api_key>

API Key (Header):

x-api-key: <your_api_key>

Installation #

1. Generate a Widget ID #

First, you need to generate a unique widget ID for your website:

POST https://api.canny.bot/api/widget/generate
x-api-key: <your_api_key>

Response:

{
  "data": {
    "widgetId": "wgt_123_abc456",
    "embedCode": "<script src=\"https://api.canny.bot/api/widget/script/wgt_123_abc456\"></script>"
  }
}

2. Embed the Script #

Copy the embed code and paste it into your website's HTML, just before the closing </body> tag:

<script src="https://api.canny.bot/api/widget/script/wgt_123_abc456"></script>

That's it! The widget will appear in the bottom-right corner of your page.

Customization #

You can customize the widget appearance by updating your user settings:

PUT https://api.canny.bot/api/widget/customize
x-api-key: <your_api_key>
Content-Type: application/json

{
  "widget_color": "#667eea",
  "widget_greeting": "Hello! How can I help you today?",
  "widget_border_radius": 16,
  "widget_button_radius": 50,
  "widget_button_text": "Chat",
  "widget_font": "Arial",
  "widget_title": "Chat with us"
}

Customization Options #

API Endpoints #

Get Widget Script #

GET https://api.canny.bot/api/widget/script/:widget_id

Returns the embeddable JavaScript widget script. This is called automatically when you include the embed code.

Parameters:

• widget_id (path): Your widget ID

Chat Endpoint #

POST https://api.canny.bot/api/widget/chat
x-api-key: <your_api_key>
Content-Type: application/json

{
  "widgetId": "wgt_123_abc456",
  "sessionId": "sess_abc123",
  "message": "What is your return policy?"
}

Response:

{
  "data": {
    "response": "Our return policy allows returns within 30 days...",
    "sessionId": "sess_abc123"
  }
}

Chat Stream Endpoint #

For real-time streaming responses, use the streaming endpoint:

POST https://api.canny.bot/api/widget/chat/stream
x-api-key: <your_api_key>
Content-Type: application/json

{
  "widgetId": "wgt_123_abc456",
  "sessionId": "sess_abc123",
  "message": "What is your return policy?"
}

Response Format (Server-Sent Events):

data: {"type":"sources","sources":[{"id":"doc_1","title":"Return Policy","url":"https://..."}]}

data: {"type":"content","content":"Our return "}

data: {"type":"content","content":"policy allows "}

data: {"type":"done"}

Get Widget Info #

GET https://api.canny.bot/api/widget/info
x-api-key: <your_api_key>

Returns current widget configuration and embed code.

Response:

{
  "data": {
    "widgetId": "wgt_123_abc456",
    "embedCode": "<script src=\"...\"></script>",
    "color": "#667eea",
    "greeting": "Hello! How can I help you today?",
    "borderRadius": 16,
    "buttonRadius": 50,
    "buttonText": "Chat",
    "font": "Arial",
    "title": "Chat with us"
  }
}

How It Works #

1. User loads your website → Widget script loads and initializes
2. Visitor clicks the chat button → Chat window opens
3. Visitor sends a message → Message is sent to /api/widget/chat/stream
4. Backend searches knowledge base → Semantic search finds relevant documents
5. AI generates response → Streamed back to the widget in real-time
6. Sources are displayed → Relevant documents shown as clickable links
7. Conversation is saved → Session history maintained for context

Knowledge Base Integration #

The widget automatically searches your knowledge base for relevant information when answering questions. It:

• Searches for documents matching the user's query
• Extracts relevant content from top 3 matching documents
• Includes context in the AI prompt
• Displays source documents as clickable links

Rate Limiting & Usage #

Each plan has a monthly interaction limit. The widget respects these limits:

• Free Plan: 100 interactions/month
• Pro Plan: 1,000 interactions/month
• Enterprise: Unlimited

When the limit is exceeded, users see a message asking them to contact the site owner.

Markdown Support #

The widget supports markdown formatting in responses:

• Bold: **text**
• Italic: *text* or _text_
• Links: [text](url)
• Code: `code`
• Strikethrough: ~text~
• Line breaks: \n

Browser Compatibility #

The widget works on all modern browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Mobile browsers (iOS Safari, Chrome Mobile)

Troubleshooting #

Widget not appearing? #

• Check that the script tag is correctly placed before </body>
• Verify the widget ID is valid
• Check browser console for errors

Responses are slow? #

• This is normal for the first response (model initialization)
• Subsequent responses should be faster
• Check your internet connection

Knowledge base not being used? #

• Ensure documents are uploaded to your knowledge base
• Verify the documents are indexed (check the Documents page)
• Try a more specific query