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 for optimal response quality
  • β€’ 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">
</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

πŸ“ System 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.4): Minimum match to use document
  • β€’ Number of Document Chunks in Context (5): How many document chunks AI receives
  • β€’ Smart Model Routing: Automatically selects better model based on query complexity
  • β€’ Automatic Support Tickets: When AI cannot answer, it offers to create a support ticket. Requires user consent and email.
  • β€’ Force Fallback: When enabled, always show fallback message for queries with low document relevance. When disabled, AI will respond even without relevant documents (conversational mode).

βš™οΈ 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)
  • β€’ Rate Limit per Minute: 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 embed code" and paste it on your website before the closing </body> tag.

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

πŸ’‘ Tip: Widget loads asynchronously and does not affect your page speed. The chat bubble appears once configuration is loaded in the background.

πŸ”΄ Note: If the chatbot is deactivated, the widget will not appear on the website at all.

⚠️ Installing via GTM: If you embed the widget through Google Tag Manager and a visitor rejects cookies, GTM won't load and the chatbot won't appear. We recommend embedding the code directly in HTML, outside of GTM.

βš™οΈ 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

  • β€’ Asynchronous loading in the background
  • β€’ Bubble appears once configuration is ready
  • β€’ 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

Current

Free

Perfect for getting started

$0/month

β€’10MB storage

β€’1 chatbot

β€’100 requests/month

β€’Basic support

β€’βœ… Conversation history

β€’βŒ Basic analytics

β€’βŒ Web URL scraping

β€’βŒ Analytics export

β€’βŒ API access

β€’βŒ Support tickets

β€’βŒ Webhook actions

β€’βŒ White-label branding

β€’βž• Buy extra requests

Trial

Evaluation

14-day trial with Enterprise features

$0/month

β€’10MB storage

β€’1 chatbot

β€’500 requests/month

β€’βœ… Conversation history

β€’βœ… Detailed analytics

β€’βœ… Web URL scraping

β€’βœ… Analytics export

β€’βœ… API access

β€’βœ… Support tickets (AI)

β€’βœ… Webhook actions (n8n)

β€’βŒ White-label branding

β€’βž• Buy extra requests

β€’Auto-downgrade to Free

Basic

For growing businesses

$15/month

β€’25MB storage

β€’1 chatbot

β€’3000 requests/month (total)

β€’Priority support

β€’βœ… Conversation history

β€’βœ… Basic analytics

β€’βŒ Web URL scraping

β€’βŒ Analytics export

β€’βŒ API access

β€’βŒ Support tickets

β€’βŒ Webhook actions

β€’βŒ White-label branding

β€’βž• Buy extra requests

Popular

Elite

Most popular

$30/month

β€’50MB storage

β€’2 chatbots (max)

β€’6000 requests/month (total)

β€’Priority support

β€’βœ… Conversation history

β€’βœ… Detailed analytics

β€’βœ… Web URL scraping

β€’βœ… Analytics export

β€’βœ… API access

β€’βŒ Support tickets

β€’βŒ Webhook actions

β€’βŒ White-label branding

β€’βž• Buy extra requests

Enterprise

Custom solutions

$50/month

β€’100MB storage

β€’3 chatbots (max)

β€’10000 requests/month (total)

β€’Premium support

β€’βœ… Conversation history

β€’βœ… Detailed analytics

β€’βœ… Web URL scraping

β€’βœ… Analytics export

β€’βœ… API access

β€’βœ… Support tickets (AI)

β€’βœ… Webhook actions (n8n)

β€’βœ… White-label branding

β€’βž• Buy extra requests

πŸ’‘ 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:

πŸ’‘ 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

All your invoices and payment history are available directly in the customer portal. You can find subscriptions, add-on purchases, and all past payments there.

πŸ”— How to Access

  1. Go to Subscription in the dashboard sidebar
  2. Click the Manage Subscription button
  3. You will be redirected to the customer portal where you can view all invoices and payment history
βš™οΈ

Settings

πŸ‘€ User Account Management

πŸ“ Change Name

Personal Information

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

πŸ“§ Change Email

After submitting the new address, confirmation links are sent to both your current and new email. The change takes effect only after clicking both links.

  • β€’ Check your current inbox and confirm from there
  • β€’ Check your new inbox and confirm from there
  • β€’ Only after both confirmations will the new email become active

πŸ”’ 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)

// 1. first request – no conversation_id needed
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?'
    // conversation_id not required – created automatically
  })
})

const result = await response.json()
const conversationId = result.data.conversation_id // save for follow-up requests

// 2. follow-up request – previous messages loaded as context
const response2 = await fetch('https://chatbotty.ai/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What about exchanges?',
    conversation_id: conversationId
  })
})

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?',
    conversation_id: conversationId // optional: to continue a conversation
  })
})

const result = await response.json()
console.log(result.data.message)
// result.data.conversation_id – save for follow-up requests

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?',
        'conversation_id': conversation_id  # optional: to continue a conversation
    }
)

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?',
    'conversation_id' => $conversationId // optional: to continue a conversation
]));

$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...",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "sources": [
      {
        "content": "Relevant document excerpt...",
        "similarity": 0.95,
        "page": 1
      }
    ],
    "metadata": {
      "tokensUsed": 150,
      "cached": false,
      "responseTime": 1234,
      "searchResults": 3
    }
  },
  "timestamp": "2025-01-28T10:00:00.000Z"
}

Error Response

{
  "success": false,
  "error": "Internal server error",
  "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)
  • β€’ Conversation context - Every response returns a conversation_id. Pass it in subsequent requests to maintain context β€” the system loads the last 20 messages automatically. Without conversation_id, each request starts a fresh standalone conversation with no context β€” this is perfectly fine if you don't need conversational memory (e.g. one-off data lookups).
  • β€’ Secure your keys - Never expose API keys in client-side code
πŸ’¬

Conversations

πŸ“ How It Works

The Conversation History feature automatically logs all chatbot sessions with comprehensive metadata for analytics, compliance, and quality assurance purposes.

  • β€’ Session Logging: Every conversation is recorded with unique session ID
  • β€’ Metadata Tracking: IP address, page URL, referrer, user agent
  • β€’ Timestamps: Precise timing for each message exchange
  • β€’ Contact Info: User-provided email and name when available

πŸ” Viewing Conversations

Access conversation history from Dashboard β†’ Conversations in the main menu.

Available Filters:

  • β€’ Period: Filter by time period (this month, last 7 days, etc.)
  • β€’ Filter (Chatbot): Show conversations for a specific chatbot or all
  • β€’ Source: Filter by source (widget, API, etc.)

Columns Displayed:

  • β€’ Session ID, Date/Time, Chatbot name
  • β€’ Message count, Source, Contact email
  • β€’ IP address (anonymized), Page URL

πŸ“‹ Conversation Details

Click on any conversation to view the full message history with detailed information.

  • β€’ Message Timeline: All user questions and AI responses
  • β€’ Timing Data: Exact timestamps for each message
  • β€’ Source Metadata: Page URL, referrer, user agent
  • β€’ Contact Information: Email and name if user provided them

πŸ’‘ Tip: Use conversation history to identify frequently asked questions and improve your chatbot's knowledge base. Patterns in user queries can help you add missing documentation.

🎫

Support Tickets

πŸ‘‘

Enterprise Feature

AI-powered support tickets are available for Enterprise tier users only.

πŸ€– How It Works

The AI Support Ticket system automatically detects when the chatbot cannot answer a user's question and offers to create a support ticket for human follow-up.

  • β€’ Smart Detection: AI recognizes when it cannot provide a satisfactory answer
  • β€’ User Consent: System asks user if they want to create a ticket
  • β€’ Email Collection: Collects user's email for follow-up
  • β€’ AI Summary: Generates a summary of the conversation for support team

πŸ“ Ticket Creation Flow

The multi-turn conversation flow for ticket creation:

  1. Trigger: AI detects unanswerable question or user expresses frustration
  2. Offer: "Would you like me to create a support ticket for you?"
  3. Consent: User confirms they want to proceed
  4. Email: "Please provide your email address for follow-up"
  5. Summary: AI generates conversation summary automatically
  6. Confirmation: Ticket created with reference number

πŸ“‹ Managing Tickets

Access and manage support tickets from Dashboard β†’ Support Tickets.

Status Workflow:

  • β€’ Open: New ticket awaiting review
  • β€’ In Progress: Support team working on the issue
  • β€’ Resolved: Issue addressed, awaiting confirmation
  • β€’ Closed: Ticket completed and archived

Available Actions:

  • β€’ View full conversation context
  • β€’ Update ticket status
  • β€’ Add internal notes
  • β€’ Send email response to user

βš™οΈ Configuration

Enable and configure support tickets in Chatbot Settings β†’ Support Tickets tab.

  • β€’ Enable/Disable: Toggle ticket creation for this chatbot
  • β€’ Email Notifications: Receive alerts for new tickets
  • β€’ Auto-response: Custom message sent to user after ticket creation
  • β€’ Triggers: Configure when ticket offers are made

πŸ’‘ Tip: Review tickets regularly to identify gaps in your knowledge base. Common ticket topics indicate areas where you should add more documentation.

πŸ”—

Webhook Actions

πŸ‘‘

Enterprise & Evaluation Feature

Webhook actions are available for Enterprise (up to 10 webhooks, up to 10 tools total across all webhooks) and Evaluation (up to 5 webhooks, up to 5 tools total across all webhooks) tier users.

πŸ”— Overview

Webhook Actions allow your chatbot to interact with external systems through AI-triggered tool calls. Define custom webhooks with specific tools that the AI can invoke during conversations.

  • β€’ Custom Webhooks: Define endpoints with authentication
  • β€’ AI Tools: Specify tools the AI can call (e.g., get_order_status)
  • β€’ Parameters: Define required and optional parameters for each tool
  • β€’ Response Handling: AI processes webhook responses naturally

βš™οΈ Setting Up Webhooks

Configure webhooks in Dashboard β†’ Webhooks for each chatbot.

  1. Create Webhook: Enter name, URL, and optional authentication headers
  2. Define Tools: Add tools the AI can call (e.g., get_order_status, check_inventory)
  3. Set Parameters: Define required parameters (e.g., order_id, product_sku)
  4. Test: Use the test feature to verify your webhook works correctly
  5. Activate: Enable the webhook for production use

πŸ”„ n8n Integration

n8n is a powerful workflow automation tool that works seamlessly with our webhook system.

Quick Setup:

  1. Create a new workflow in n8n
  2. Add a Webhook trigger node (POST method)
  3. Copy the webhook URL to your chatbot webhook configuration
  4. Build your workflow logic (API calls, database queries, etc.)
  5. Return JSON response that the AI will process

Example Response Format:{"status": "shipped", "tracking": "1Z999AA1", "eta": "2024-01-15"}

πŸ’‘ Example Use Cases

πŸ“¦ Order Status Lookup

Customer asks "Where is my order?" β†’ AI calls get_order_status with order number β†’ Returns tracking info

πŸ‘€ CRM Integration

User provides email β†’ AI calls lookup_customer β†’ Returns account details and recent activity

πŸ“… Appointment Booking

User requests appointment β†’ AI calls check_availability then book_appointment β†’ Confirms booking

πŸ” Inventory Check

Customer asks about product availability β†’ AI calls check_stock β†’ Returns current inventory

πŸ”’ Security

  • β€’ HTTPS Required: All webhook endpoints must use HTTPS
  • β€’ Custom Headers: Add authentication tokens in headers
  • β€’ Timeout Handling: 30-second timeout prevents hanging requests
  • β€’ SSRF Protection: Private IP addresses are blocked for security
  • β€’ Rate Limiting: Built-in protection against excessive calls

⚠️ Important: Never expose sensitive API keys in webhook URLs. Use authentication headers instead.

πŸ’‘ Tip: Start with simple read-only operations (like order lookup) before implementing write operations. Test thoroughly using the built-in webhook tester before activating in production.

πŸ’‘

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.

πŸ’‘ Tips for Getting the Most Value

Get better answers from your chatbot and make the most of your monthly message quota with these tips:

πŸ“„ Document Quality:
  • β€’ Remove unnecessary content before upload β€” cleaner documents = more accurate answers
  • β€’ Use well-structured documents with clear headings and sections
  • β€’ Avoid duplicate information across documents
❓ Encourage Good Questions:
  • β€’ Specific, focused questions get better answers than vague ones
  • β€’ Well-prepared documents lead to faster, more precise responses
πŸ“Š Monitor Your Usage:
  • β€’ Track your message quota in dashboard analytics
  • β€’ For seasonal traffic spikes, use extra message add-ons instead of upgrading your plan
  • β€’ Review monthly trends to decide if your current plan fits your needs
πŸ”§

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

πŸ†˜ 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)