Chatbot Builder - Help

Chatbot Builder - Help

Complete guide for creating AI chatbots from various documents and web sources

πŸ“–

Overview

Chatbot Builder (Chatbotty.ai) is a Redis Cache optimized platform for creating AI chatbots from various documents and web sources. It serves everyone who needs to provide quality answers to user queries based on current documents and sources - government offices, organizations, businesses, and individuals.

✨ Key Features

πŸ€– AI and Processing

  • β€’ AI chatbots from various documents and web sources
  • β€’ Smart AI routing (GPT-4.1 mini β†’ GPT-4.1)
  • β€’ Vector database for semantic search
  • β€’ Advanced chunking by document type

⚑ Performance and Reliability

  • β€’ Multi-level caching (Memory β†’ Redis β†’ PostgreSQL)
  • β€’ Asynchronous widget without page speed impact
  • β€’ Protection against abuse and bot attacks
  • β€’ Flexible rate limits for individual chatbots

πŸ“Š Management and Analytics

  • β€’ Extensive personalization and configuration options
  • β€’ Automatic document replacement with new versions
  • β€’ Real-time analytics and quality optimization
  • β€’ Automatic subscription and tier management

🎯 Ideal for

  • Government offices and public institutions

    Automation of information services for citizens, answers to frequent questions about official procedures

  • E-commerce and online services

    Smart customer support without call center, handling orders and complaints

  • Companies with extensive documentation

    Quick search in internal resources, onboarding new employees

  • Educational institutions

    Support for students and answers to frequent questions, information about study programs

  • Healthcare Facilities

    Patient information and administrative support, patient guides

  • Law Offices

    Quick access to legal documents and precedents, legal case analysis

  • IT and Technology Companies

    Technical support automation and API documentation, solving common problems

  • Consulting Companies

    Sharing expertise and best practices, internal knowledge base

  • Marketing Agencies

    Customer needs analysis and content optimization, creative brief assistance

πŸš€

Getting Started

🎯 Quick Guide

  1. 1
    Registration and Login

    Create your account. You automatically get Evaluation tier for 14 days with 3,000 messages/month (more than Elite's 500) plus all Elite features.

  2. 2
    Creating Your First Chatbot

    Click "New Chatbot" β†’ enter name and description β†’ choose response style (formal/friendly/professional). After creation, you'll be redirected to detailed settings where you can customize all chatbot parameters according to your needs.

  3. 3
    Document Upload

    Drag & drop PDF/DOCX/TXT/MD files or enter web page URL. You can choose document type for optimal chunking strategy (legal, technical, academic, news, general).

  4. 4
    Testing and Embedding

    Test the chatbot in preview mode β†’ copy embed code β†’ insert on your website

⚑ Quick Tips for Getting Started

πŸ“„ Document Preparation

  • β€’ Structure: Use clear headings, bullets, and numbering
  • β€’ Format: PDF with readable text (not scanned images)
  • β€’ Size: File size affects processing speed
  • β€’ Content: Remove duplicates and irrelevant parts
  • β€’ Language: Consistent terminology and style
  • β€’ Metadata: Clear file names for better organization
  • β€’ Currency: Use the latest document versions

🎨 Widget Integration

Simple integration using JavaScript code:

<script 
  src="https://chatbotty.ai/chatbot-embed.js" 
  data-chatbot-id="xxxxxxxx"
  data-base-url="https://chatbotty.ai">
</script>
  • β€’ Asynchronous loading without page blocking
  • β€’ Cross-domain support
πŸ€–

Chatbot Management

βž• Creating Chatbots

🎯 Basic Configuration

Basic information:

  • β€’ Chatbot name: Identification of your chatbot
  • β€’ Description: Brief description of the chatbot's purpose
  • β€’ Response style: Formal / Friendly / Professional / Informal

🎨 Appearance

Customizing chatbot widget appearance:

  • β€’ Theme color: Selection from preset colors
  • β€’ Welcome message: Text for first contact with user
  • β€’ Error message: Text displayed when chatbot is unavailable
  • β€’ Allowed domains for embedding: Specify where widget can be used

πŸ’Ž Maximum Number of Chatbots by Plan

Free

1 chatbot

Evaluation

1 chatbot

14 days trial

Basic

1 chatbot

Elite

2 chatbots

Enterprise

3 chatbots

πŸ—‘οΈ Delete Confirmation

⚠️

Safe Deletion Process

When deleting a chatbot, a confirmation dialog appears to prevent accidental deletion. This ensures you don't lose important data by mistake.

⚠️ Warning:

All chatbot data, documents, and analytics will be permanently removed and cannot be recovered.

πŸ”§

Advanced Chatbot Settings

🧠 AI Behavior and Prompts

πŸ“ Basic Instructions

Define the personality and behavior of the AI assistant. Contains guidelines for:

  • β€’ Communication style and response tone
  • β€’ General behavior and rules
  • β€’ Critical instructions for limitations
🏷️ Available Placeholders

The following placeholders can be used in instruction prompts and messages:

  • β€’ {current_datetime} - Current date and time
  • β€’ {chatbot_id} - Unique chatbot identifier
  • β€’ {fallback_message} - Custom fallback message when no answer found

⚑ Search and Response Quality

πŸ” Search Parameters

  • β€’ Similarity threshold (0.3): Minimum match to use document
  • β€’ Documents in context (5): How many documents AI receives
  • β€’ "Answered" threshold (0.45): When to consider response complete
  • β€’ "Partial" threshold (0.3): When to consider response partial
  • β€’ Intelligent model routing: Automatically selects suitable model based on query complexity
  • β€’ Conversation memory: Chatbot remembers previous messages within one session

βš™οΈ Language Preferences and AI Parameters

  • β€’ Chatbot response language: Language in which chatbot will respond
  • β€’ Timezone: For responses about current date and time
  • β€’ Creativity (Temperature): 0.0 = precise, 1.0 = creative responses
  • β€’ Maximum response length (tokens): Limit in tokens (β‰ˆ 375 words for 500 tokens)

πŸ›‘οΈ Anti-spam Protection

  • β€’ Max requests/day: Maximum number of requests from one IP address per 24 hours (anti-bot protection)
  • β€’ Max requests/session: Maximum number of requests per session (2-hour window for abuse prevention)
  • β€’ Request limit/min: Protection against spam queries
  • β€’ Cache TTL (seconds): How long to cache responses

πŸ”„ Reset to Defaults

πŸ”„

Restore Default Settings

The 'Reset to Defaults' button restores all advanced settings to their default values. A confirmation dialog appears before resetting to prevent accidental changes.

ℹ️ Note:

You can always reset your settings back to the defaults if you want to start fresh or if something isn't working as expected.

πŸ“„

Document Management

πŸ“€ File Upload

πŸ“‹ Supported Sources

πŸ“„

Files

PDF, DOCX, TXT, MD, HTML

Elite+
🌐

Web URL

Automatic scraping

πŸ”„

Updates

Automatic version replacement

🎯 Optimal Document Preparation

βœ… Recommended practices:

  • β€’ Clear headings and structure
  • β€’ PDF with readable text (not images)
  • β€’ Consistent formatting
  • β€’ Logical section numbering

❌ Avoid:

  • β€’ Scanned images without OCR
  • β€’ Excessive text fragmentation
  • β€’ Inconsistent formatting
  • β€’ Files larger than 10MB

πŸ’Ύ Storage Limits by Plan

Free

10MB total

Evaluation

20MB total

Basic

10MB total

Elite

20MB total

Enterprise

50MB total

πŸ“‹ Duplicate Detection

πŸ“‹

Smart Duplicate Handling

When uploading a document with the same name as an existing one, a confirmation dialog appears with options to prevent accidental overwrites.

Available Options:

  • β€’ Replace: Overwrites the existing document with the new version
  • β€’ Keep Both: Keeps both versions (new file gets a numbered suffix)

πŸ“„ Document Upload Process

1

Select chatbot

Choose chatbot to which the document will be assigned

2

Select upload method

πŸ“Ž Files (PDF, DOCX, TXT, MD)

Maximum 10 MB per file

Elite+

🌐 Web URL

Automatic web page scraping

3

Select document type

System automatically optimizes processing by type:

βš–οΈ

Legal document:

Laws, regulations, contracts

πŸ”§

Technical manual:

Guides, specifications, procedures

πŸ“°

News:

Articles, press releases

πŸŽ“

Academic text:

Scientific papers, studies

πŸ“„

General document:

Universal settings

4

Describe document (optional)

Add description for easy future navigation in document list

πŸ’‘

File update tip

When entering the same document name, you have the option of automatic replacement of the original version without having to delete the outdated document. Your data will stay current.

πŸ’¬

Chat Widget

πŸ”§ Web Embedding (displaying chatbot on your website)

πŸ“‹ Getting Embed Code

You can find the embed code for each chatbot in the context menu (three dots). Click "Copy Code" and paste it on your website before the closing </body> tag.

<script 
  src="https://chatbotty.ai/chatbot-embed.js" 
  data-chatbot-id="xxxxxxxx"
  data-base-url="https://chatbotty.ai">
</script>

πŸ’‘ Tip: Widget loads asynchronously and does not affect your page speed. Initial display is instant (~50ms) with skeleton, data loads in background.

βš™οΈ Widget Configuration

You can fully customize the widget in the "Appearance" section when editing the chatbot. All settings are automatically applied to the embed code.

🎨 Appearance and position:

  • β€’ Theme color: 6 preset colors (blue, red, green, yellow, purple, orange)
  • β€’ Widget position: Bottom right / Bottom left
  • β€’ Welcome message: User greeting
  • β€’ Fallback message: Text for cases when chatbot doesn't know the answer to a question

βš™οΈ Chatbot behavior:

  • β€’ Chatbot name: Displayed in header
  • β€’ Description: Short description of chatbot purpose (not displayed on web)
  • β€’ Response style: Professional, friendly, formal
  • β€’ Status: Active/inactive chatbot

🎯 Widget Customization

Position Options:

  • β€’ Bottom-right (default)
  • β€’ Bottom-left

Bubble Effects:

  • β€’ Pulse effect - Animated bubble to attract attention (can be toggled on/off)

πŸ‘οΈ Widget Preview

Use the widget preview modal to test your chatbot before embedding:

  • β€’ Click "Preview" button in chatbot settings
  • β€’ Opens widget in modal window
  • β€’ Test all features and appearance
  • β€’ No code installation needed

πŸ”— Public Widget Page

Access your widget at: /widget-embed/[widgetId]

  • β€’ Standalone page for testing
  • β€’ Can be shared with team members
  • β€’ No website integration required

πŸ’‘ Tip: All changes take effect immediately on all websites with embedded widget. No need to change code.

⚑ Performance Optimization

πŸš€ Asynchronous loading

  • β€’ ~50ms instant display of widget skeleton
  • β€’ Background data loading
  • β€’ Zero impact on main page speed
  • β€’ Progressive enhancement

πŸ’Ύ Smart Cache

  • β€’ 90%+ cache hit rate
  • β€’ 5-minute configuration validity
  • β€’ Fast loading via Redis
  • β€’ Smooth operation even during Redis Cache outage

πŸ”’ Security and Restrictions

🌐 Domain restrictions

Limit access only to allowed domains:

Configuration example:

  • β€’ example.com
  • β€’ *.example.com (including subdomains)

πŸ›‘οΈ Anti-spam Protection

Request limit settings for protection against spam and abuse

Max requests/day

50

Maximum number of requests from one IP address per 24 hours (anti-bot protection)

Max requests/session

20

Maximum number of requests per session (2-hour window for abuse prevention)

Request limit/min

10

πŸ›‘οΈ Protection against spam queries

Cache TTL (seconds)

300

⚑ How long to cache responses

πŸ“ Note:

These parameters are fully user-configurable in advanced settings of each chatbot for maximum flexibility.

πŸ“Š

Analytics

🎯 Access by Plan

πŸ†“ Free

No access

Upgrade popup with instructions

⭐ Evaluation

Full access

14 days of Elite-level features

πŸ”΅ Basic

Basic metrics

  • β€’ Message counts
  • β€’ Top queries
  • β€’ Chatbot stats

πŸ‘‘ Elite+

Detailed analytics

  • β€’ Success rate
  • β€’ Data export
  • β€’ Detailed reports
  • β€’ Interactive interface
  • β€’ Analytics for each chatbot separately

πŸ€– Detailed Chatbot AnalyticsElite+

πŸ“‹ Display for each chatbot

  • β€’ Individual overview: Separate analytics for each chatbot
  • β€’ Query filtering: Display only relevant conversations
  • β€’ Isolated metrics: Individual chatbot performances separated
  • β€’ Chatbot comparison: Ability to compare performance of different bots

πŸ” Detailed query display

  • β€’ Complete query: Display of entire question from user
  • β€’ Response reliability: Exact confidence score value
  • β€’ AI response: Complete text of chatbot response
  • β€’ Timestamp: Date and time of each query

πŸ’‘ Practical use: Enables precise analysis of how individual chatbots respond to user queries, identification of problem areas and document optimization for each chatbot separately.

πŸ“ˆ Available Metrics

🎯 Main KPIs

πŸ“Š
Total queries
Number of all messages per period
βœ…
Success rate
Percentage of complete answers
⚠️
Partial answers
Percentage of partial answers
πŸ“ˆ
Average reliability
Document similarity score

πŸ“Š Response Quality

βœ… AnsweredXX%
Full answer found
⚠️ PartialXX%
Partial answer
❌ No answerXX%
Answer not found

⚠️ Data History Limitations by Plan

Data corresponding to the maximum number of queries per month according to your plan is retained. Older data is automatically deleted for database performance optimization.

  • β€’ Free: 200 queries
  • β€’ Basic: 3000 queries
  • β€’ Elite: 6000 queries
  • β€’ Enterprise: 10000 queries

πŸ“€ Export and Reports

πŸ“‹ Availability: Export functionality is available only for Elite+ plans (Elite and Enterprise).

πŸ’‘ Tip: We recommend exporting data on the last day of each month to track full customer query history.

πŸ’Ύ Export Formats

  • β€’ CSV: Tabular data for Excel
  • β€’ JSON: Structured data for API

πŸ” Data Filters

πŸ• Time filters:

  • β€’ This week: Last 7 days
  • β€’ This month: Current month
  • β€’ This year: Current year

πŸ“‹ Filters by response:

  • β€’ All queries: Complete history
  • β€’ βœ“ Answered: Successful responses
  • β€’ ⚠ Partially answered: Incomplete responses
  • β€’ βœ— Unanswered: No response
πŸ’Ž

Subscription

🎯 Plan Overview

AktuΓ‘lnΓ­

Free

Perfect for getting started

$0/mΔ›sΓ­c

β€’0MB storage

β€’0 chatboti (max)

β€’0 dotazΕ―/mΔ›sΓ­c

β€’ZΓ‘kladnΓ­ support

β€’βŒ ZΓ‘kladnΓ­ analytika

β€’βŒ Web URL scraping

β€’βŒ Export analytiky

β€’βŒ API pΕ™Γ­stup

β€’βž• PΕ™ikup extra dotazΕ―

Trial

Evaluation

14-day trial with Elite features

$0/mΔ›sΓ­c

β€’0MB storage

β€’0 chatboti (max)

β€’0 dotazΕ―/mΔ›sΓ­c

β€’Elite features 14 dnΓ­

β€’βœ… DetailnΓ­ analytika

β€’βœ… Web URL scraping

β€’βœ… Export analytiky

β€’βœ… API pΕ™Γ­stup

β€’βž• PΕ™ikup extra dotazΕ―

β€’Auto-downgrade to Free

Basic

For growing businesses

$0/mΔ›sΓ­c

β€’0MB storage

β€’0 chatboti (max)

β€’0 dotazΕ―/mΔ›sΓ­c (celkovΔ›)

β€’Priority support

β€’βœ… ZΓ‘kladnΓ­ analytika

β€’βŒ Web URL scraping

β€’βŒ Export analytiky

β€’βŒ API pΕ™Γ­stup

β€’βž• PΕ™ikup extra dotazΕ―

Popular

Elite

Most popular

$0/mΔ›sΓ­c

β€’0MB storage

β€’0 chatboti (max)

β€’0 dotazΕ―/mΔ›sΓ­c (celkovΔ›)

β€’Priority support

β€’βœ… DetailnΓ­ analytika

β€’βœ… Web URL scraping

β€’βœ… Export analytiky

β€’βœ… API pΕ™Γ­stup

β€’βž• PΕ™ikup extra dotazΕ―

Enterprise

Custom solutions

$0/mΔ›sΓ­c

β€’0MB storage

β€’0 chatboti (max)

β€’0 dotazΕ―/mΔ›sΓ­c (celkovΔ›)

β€’Premium support

β€’βœ… DetailnΓ­ analytika

β€’βœ… Web URL scraping

β€’βœ… Export analytiky

β€’βœ… API pΕ™Γ­stup

β€’βž• PΕ™ikup extra dotazΕ―

πŸ’‘ Data Usage

10MB of data corresponds to approximately 1000 pages of PDF document. In purely text formats, even much more.

Warning: The original size of the uploaded file counts towards data limits. Embedded images in documents can significantly increase the uploaded file size.

πŸ’° Annual Subscription

Save 2 months with annual billing – pay for 10 months only!

Annual billing offers significant savings compared to monthly payments. You can change your billing period or subscription at any time.

⏰ Trial Period Expiration

  • β€’ Automatic downgrade to Free plan after 14 days
  • β€’ Seamless transition without data loss

πŸ“Š Usage Tracking

πŸ“Š Dashboard Tracking

Track your plan usage directly in real-time:

πŸ“ˆ Monthly Limits
  • β€’ Number of messages per month
  • β€’ Forecast until end of month
  • β€’ Automatic reset every month
πŸ“‹ Permanent Limits
  • β€’ Storage capacity (MB/MB)
  • β€’ Number of chatbots (count/limit)
πŸ“Š Statistics
  • β€’ Total created chatbots
  • β€’ Active and functional chatbots
  • β€’ Total queries from users
  • β€’ Uploaded documents
πŸ“ˆ Visualization
  • β€’ Colored progress bars
  • β€’ Real-time tracking

⚠️ Limit Enforcement

  • β€’ Storage exceeded: Upload blocked with upgrade prompt
  • β€’ Chatbot limit: Creation blocked, upgrade dialog shown
  • β€’ Monthly messages: Widget won't load (silent failure)
  • β€’ Analytics access: Feature restrictions by plan

πŸ’° Extra Messages Add-ons

Extra messages are additional message packages you can purchase to extend your monthly quota. Unlike monthly subscriptions, extra messages never expire and persist across billing cycles.

πŸ”„ How it works:

  1. Your monthly quota is consumed first
  2. When monthly quota is exhausted, extra messages are automatically used
  3. Extra messages persist until fully consumed (no expiration)
  4. Visible on dashboard with real-time tracking

πŸ“¦ Available Packages:

1,000 messages

$3.99

(no expiration)

5,000 messages

$14.99

(no expiration)

10,000 messages

$24.99

(no expiration)

πŸ’‘ When to buy:

  • β€’ Seasonal traffic spikes
  • β€’ Special campaigns
  • β€’ Testing before upgrade
  • β€’ One-time high usage

πŸ’³ Purchase: Click "Buy Extra Messages" on dashboard or in usage tracking card when approaching limit.

πŸ“„

Invoices

πŸ“‹ Overview

Track all your billing history including subscriptions, add-ons, and upgrades in one place.

πŸ“ Invoice Types

πŸ’Ž Subscription

Monthly/yearly subscription charges

βž• Add-on

Extra messages purchases

⬆️ Upgrade

Tier upgrade charges

🏷️ Invoice Statuses

βœ… Paid

Successfully processed

⏳ Open

Awaiting payment

❌ Void

Cancelled

πŸ“ Draft

Not yet finalized

⚑ Actions

  • β€’ Download PDF invoice - Save invoice as PDF file
  • β€’ Open in Stripe - View detailed information
  • β€’ Filter by type - Show specific invoice types
  • β€’ Sort by date - Organize chronologically

πŸ” Access

Available at /dashboard/invoices for users with active Stripe subscriptions.

βš™οΈ

Settings

πŸ‘€ User Account Management

πŸ“ Change Name

Personal Information

  • β€’ Name: Displayed username
  • β€’ Can be changed anytime
  • β€’ Shows in profile and communication

πŸ“§ Change Email

After changing your email, you will need to confirm the new address via email that we will send you.

  • β€’ Email: Login email address
  • β€’ New address confirmation required
  • β€’ Used for login and notifications

πŸ”’ Change Password

Password must be at least 6 characters

Password requirements:

  • β€’ Minimum 6 characters
  • β€’ Combination of letters and numbers
  • β€’ Current password required

Forgotten password:

  • β€’ Reset via email
  • β€’ Secure reset link
  • β€’ Immediate delivery

🌐 Language Settings

Switch between English and Czech interface

  • β€’ Click language selector in top navigation
  • β€’ Available languages: English (EN) / Czech (CS)
  • β€’ Automatic page reload - The page automatically reloads after language change to apply all translations
  • β€’ Language preference is saved to your account

⚠️ Danger Zone

Actions in this section are irreversible. Proceed with caution.

⚠️ Deleting your account will permanently remove all your data, chatbots, documents and conversations. This operation is irreversible.

The "Delete Account" button will trigger complete removal of all data from the database.

πŸ”—

API

πŸš€ Programmatic Access to Chatbots

πŸ’Ž Available for Higher Tiers

API access is available for users with Evaluation, Elite and Enterprise subscription tiers. It allows you to integrate your chatbots into custom applications, websites, or systems.

πŸ“‹ What You Get

  • β€’ REST API: Standard HTTP requests
  • β€’ Code Examples: JavaScript, Python, PHP, Node.js
  • β€’ Chatbot ID: Unique identifier for each chatbot
  • β€’ Complete Documentation: Available directly in the app

πŸ’‘ How to Get Started: After logging into the application, you'll find the "API Integration" section in the menu, where you can access detailed instructions including connection examples for various programming languages and test samples.

πŸ” API Authentication

How it works

API access uses Bearer token authentication. Each API key is tied to a specific chatbot.

  1. Create API key in Dashboard β†’ API Integration for your chatbot
  2. Include API key in Authorization header as Bearer token
  3. Send POST request to /api/chat endpoint
  4. Chatbot is automatically identified from the API key

Important: You do NOT need to send chatbot_id in the request body. The chatbot is determined from your API key.

πŸ”‘ API Keys Management

Create API Keys

Generate secure API keys for programmatic access to your chatbots.

Features:

  • β€’ Custom names - Label keys for easy identification
  • β€’ Max 50 keys - Per chatbot limit
  • β€’ Secure tokens - Full token shown only once at creation
  • β€’ Activity tracking - Last used timestamp
  • β€’ Toggle active/inactive - Temporary disable without deletion

Security:

  • β€’ Tokens are masked in UI (show first/last characters only)
  • β€’ Copy to clipboard for easy use
  • β€’ Delete compromised keys immediately

⚑ Monthly Quota: API usage counts against your monthly message limit. Extra messages can be purchased when quota is exceeded.

πŸ’» Code Examples

JavaScript (Browser)

const response = await fetch('https://chatbotty.ai/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What is your return policy?'
  })
})

const result = await response.json()
console.log(result.data.message)

Node.js

const response = await fetch('https://chatbotty.ai/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What is your return policy?'
  })
})

const result = await response.json()
console.log(result.data.message)

Python

import requests

response = requests.post(
    'https://chatbotty.ai/api/chat',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'message': 'What is your return policy?'}
)

result = response.json()
print(result['data']['message'])

PHP

<?php
$ch = curl_init('https://chatbotty.ai/api/chat');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'message' => 'What is your return policy?'
]));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['data']['message'];
?>

cURL

curl -X POST https://chatbotty.ai/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your return policy?"}'

πŸ“‹ Response Format

Successful Response

{
  "success": true,
  "data": {
    "message": "AI response text...",
    "sessionId": "optional-session-id",
    "sources": [
      {
        "content": "Relevant document excerpt...",
        "similarity": 0.95,
        "page": 1
      }
    ],
    "metadata": {
      "model": "gpt-4.1-mini",
      "tokensUsed": 150,
      "responseTime": 1234,
      "searchResults": 3
    }
  },
  "timestamp": "2025-01-28T10:00:00.000Z"
}

Error Response

{
  "success": false,
  "error": "Invalid or inactive API key",
  "timestamp": "2025-01-28T10:00:00.000Z"
}

⚠️ Important Notes

  • β€’ API keys are chatbot-specific - Each key works with one chatbot only
  • β€’ Up to 50 keys per chatbot - Create multiple keys for different applications
  • β€’ Keys can be disabled - Temporarily deactivate without deletion
  • β€’ Monthly quota applies - Limited by your subscription tier messages/month + extra messages purchased
  • β€’ No per-minute rate limiting - API is designed for programmatic access without rate limits
  • β€’ No domain validation - API works from any origin (use with caution)
  • β€’ Session support - Include optional sessionId for conversation history
  • β€’ Secure your keys - Never expose API keys in client-side code
πŸ’‘

Tips & Tricks for Document Preparation and Successful Chatbot Implementation

πŸ“„ Document Preparation

πŸ“‹ Content Structuring

  • β€’ Thematic division: One file = one topic
  • β€’ Logical structure: Clear sections and headings
  • β€’ Easy updates: Change only relevant parts
  • β€’ Clarity: Quick content orientation

πŸ“ Format and Naming

  • β€’ Text formats: TXT, DOC, DOCX (without images)
  • β€’ Clear names: Descriptive file names
  • β€’ Auto-update: Same name = replacement
  • β€’ Worry-free: Old version deleted automatically

πŸ’‘ Tip: Prepare documents in advance in plain text format. Images and complex formatting can worsen chatbot response quality.

🎯 Semantic Search

πŸ” How Chatbot Finds Answers

  • β€’ Semantic matching: Searches for similar meaning, not exact text
  • β€’ Keywords: Identifies important terms in query
  • β€’ Context: Considers entire sentence meaning
  • β€’ Similarity: Compares with existing information

✍️ Optimal Formulation

  • β€’ Direct answers: "X is Y years old" instead of "X celebrated Y years"
  • β€’ Various formulations: Use different ways of expression
  • β€’ Expected questions: Think about possible user queries
  • β€’ Keywords: Include synonyms and variants

❌ Less suitable:

"Big Ben celebrated its 165th anniversary"

βœ… Better:

"Big Ben is 165 years old"

Why: The second version better answers questions like "How old is Big Ben?" or "What is the age of Big Ben?"

πŸ“Š Analytics-Based Optimization

πŸ” Gap Analysis

  • β€’ Unanswered queries: Track frequent questions without answers
  • β€’ Low reliability: Identify queries with low confidence
  • β€’ Recurring problems: Find patterns in unsuccessful queries
  • β€’ User frustrations: Observe points where users get "stuck"

🎯 Targeted Improvements

  • β€’ Document expansion: Add missing information
  • β€’ Reformulation: Clarify unclear passages
  • β€’ New formulations: Add different ways of expression
  • β€’ Test and iterate: Test changes and measure improvements
πŸ’― Reliability Interpretation

< 30%

Unsuccessful answer

30-40%

Partially answered

> 40%

Successful answer

πŸ’‘ Tip: Test your modifications directly in the chatbot. Ask the same questions again and monitor reliability changes. The goal is to consistently achieve over 40% reliability.

Why such low values? For 100% reliability, the query would need to be identified exactly in the same wording in the document, which happens very rarely. Therefore, realistic values for English environment are lower.

❓ FAQ Optimization

πŸ“ˆ Most Frequent Queries Analysis

  • β€’ Track trends: Identify recurring questions
  • β€’ Prioritization: Focus on most frequent queries
  • β€’ Patterns: Look for similar formulations of the same question
  • β€’ Problems: Find queries with low reliability

πŸ“ FAQ Document Creation

  • β€’ One paragraph = Q&A: Question and answer together
  • β€’ Natural language: Use common formulations
  • β€’ Complete answers: All necessary information at once
  • β€’ Various variants: Include synonyms and alternatives
✨ Optimized FAQ Example

How long does passport application processing take?Passport application processing takes a standard 6-8 weeks from submission of a complete application. For urgent travel needs, expedited processing is available within 2-3 weeks for an additional $60 fee. You can collect your passport in person at the application center or have it mailed to your address.

πŸš€ Result: FAQ document dramatically increases reliability of answers to most frequent queries. You'll satisfy 80-90% of user questions with high accuracy.

πŸ“Š Long-term Analysis

πŸ” Regular Monitoring

  • β€’ Weekly check: Track unsuccessful answers
  • β€’ Monthly overview: Analyze trends and changes
  • β€’ Partial answers: Identify areas for improvement
  • β€’ Problem patterns: Find recurring deficiencies

πŸ“€ Analytics exportElite+

  • β€’ CSV format: For MS Excel and Numbers
  • β€’ Detailed data: All queries and answers
  • β€’ Reliability: Confidence level for each query
  • β€’ Timestamp: Tracking trends over time
πŸ“ˆ Recommended Workflow

1. Weekly export

Download data from last week

2. Excel Analysis

Filter by reliability < 40%

3. Updates

Modify documents based on insights

πŸ’‘ For advanced users: Use Excel pivot tables to group similar queries and identify the most common problem areas.

🌐 Using Web Sources

πŸ”— Web URL scrapingElite+

  • β€’ Direct import: Load content from websites
  • β€’ FAQ sections: Ideal for existing Frequently Asked Questions
  • β€’ Documentation: Use existing ready-made documentation
  • β€’ Current content: Always the latest version of information

βœ… Web Scraping Benefits

  • β€’ Time saving: No manual rewriting
  • β€’ Data consistency: No differences between websites and chatbot
  • β€’ Automatic updates: Just reload the URL
  • β€’ Structured content: Formatting is preserved
πŸ“‹ Ideal Sources for Scraping

βœ… Suitable pages:

  • β€’ FAQ sections
  • β€’ Product documentation
  • β€’ Guides and procedures
  • β€’ Contact information

❌ Less suitable:

  • β€’ Pages with many images
  • β€’ Navigation menus
  • β€’ Advertisement content
  • β€’ JavaScript generated content

πŸ’‘ Tip: If you have quality FAQ or documentation on your website, use URL scraping instead of manual rewriting. This prevents inconsistency and saves time during updates.

πŸ’° Cost Optimization

Token Usage Optimization

Reduce message consumption with these strategies:

πŸ“„ Document Preparation:
  • β€’ Remove unnecessary content before upload
  • β€’ Use concise, well-structured documents
  • β€’ Avoid duplicate information across documents
  • β€’ Smaller chunks = less token usage per query
βš™οΈ AI Configuration:
  • β€’ Set appropriate max_response_length (default: 500 tokens)
  • β€’ Use shorter instruction prompts when possible
  • β€’ Enable force_fallback for simple FAQ scenarios (no document search = no embedding costs)
  • β€’ Lower context_chunks if 5 is too many (try 3-4 for specific topics)
❓ Query Patterns:
  • β€’ Encourage users to ask specific questions
  • β€’ Short, focused queries use fewer tokens than broad questions
  • β€’ Well-prepared documents lead to faster, cheaper answers
βœ… Smart Caching Benefits
  • β€’ Identical queries are cached (no AI cost for repeated questions)
  • β€’ Document embeddings are cached (only computed once per document)
  • β€’ Content hashing prevents duplicate processing
  • β€’ Multi-level caching (Memory β†’ Redis β†’ PostgreSQL) reduces database load
πŸ“Š Message Tracking:
  • β€’ Monitor usage in dashboard analytics
  • β€’ Track query patterns to optimize document structure
  • β€’ Use extra messages add-ons for traffic spikes instead of upgrading tier
  • β€’ Review monthly usage trends to choose optimal plan
πŸ”§

Troubleshooting

⚠️ Common Issues

πŸ€– Chatbot Not Responding

Possible causes:

  • β€’ Monthly message limit exceeded
  • β€’ Domain is blocked by restrictions
  • β€’ Rate limiting activated
  • β€’ Widget loading error

Solution:

  • β€’ Check usage in dashboard
  • β€’ Verify allowed domains
  • β€’ Browser developer tools β†’ Network tab
  • β€’ Contact support with error details

πŸ“„ Document Not Processing

Common problems:

  • β€’ File larger than plan limit
  • β€’ Unsupported format
  • β€’ Corrupted or password-protected PDF
  • β€’ Processing queue overload

Diagnostics:

  • β€’ Check file size vs plan limit
  • β€’ Try selecting text in PDF
  • β€’ Processing status in documents
  • β€’ Retry upload if stuck

🌐 Widget Won't Load

Loading problems:

  • β€’ CORS policy blocking
  • β€’ Script loading timeout
  • β€’ CSP (Content Security Policy)
  • β€’ Ad blocker interference

Solution steps:

  • β€’ Error messages in browser console
  • β€’ Try different browser/incognito
  • β€’ Temporarily disable ad blockers
  • β€’ Check allowed domains settings

πŸ” Health Check & Debugging

System Health Endpoints

Use these endpoints to verify system status:

Main Health Check:

GET https://chatbotty.ai/api/health

Returns: { "status": "ok", "timestamp": "..." }

Redis Cache Health:

GET https://chatbotty.ai/api/health/redis?test=true

Returns: Cache status and connection test results

When to Use:

  • β€’ Verifying system availability
  • β€’ Debugging connectivity issues
  • β€’ Monitoring uptime

Graceful Degradation:

The system works without Redis cache. If Redis is unavailable, the platform automatically falls back to direct database queries with slightly slower performance.

Browser Console Debugging

  1. Open browser Developer Tools (F12)
  2. Go to Console tab
  3. Look for errors starting with "Chatbot Error:" or "Widget Error:"
  4. Check Network tab for failed API requests
  5. Include console errors in support requests

πŸ†˜ Support Contact

πŸ“§ Email Support

support@chatbotty.ai

  • β€’ Priority plans: within 24h (exceptionally up to 48h)
  • β€’ Free plans: usually within 72h
  • β€’ Attachments: Screenshots, logs welcome

πŸ” What to Include

  • β€’ Browser type and version
  • β€’ Error message or screenshot
  • β€’ Chatbot ID and widget URL
  • β€’ Reproduction steps
  • β€’ Console errors (F12)