EXECUTIVE VISION: GENERAL BOTS PLATFORM

OPEN SOURCE ENTERPRISE AI PLATFORM

General Bots 6.1 delivers enterprise-grade AI capabilities with full data sovereignty. Own your infrastructure, control your data, deploy anywhere.

INVESTOR HIGHLIGHTS

FEATURE OVERVIEW

LLM-ASSISTED ATTENDANT FEATURES

When conversations transfer from bot to human, the LLM continues working as a copilot:

WhatsApp Commands for Attendants:

/queue    - View waiting customers
/take     - Take next conversation
/tips     - Get AI tips
/polish   - Improve message
/replies  - Get suggestions
/summary  - Conversation summary
/resolve  - Mark complete

DEPLOYMENT OPTIONS

Option 1: Pragmatismo Managed Hosting

• Fully managed infrastructure
• Access via: YourCompany.pragmatismo.com.br
• Professional support included
• Complete data ownership

Option 2: Self-Hosted

• Deploy on your own infrastructure
• Full control over hardware and configuration
• Access via your own domain
• No external dependencies

Option 3: Hybrid Deployment

• Run locally with cloud backup
• Export everything as ZIP anytime
• Move between hosting options freely
• No vendor lock-in

COMPETITIVE ADVANTAGE

TECHNICAL ARCHITECTURE

FEATURE TIERS

Core Edition (Default)

• UI Server
• Console Interface
• Chat functionality
• Automation engine
• Task management
• Drive integration
• LLM support
• Redis caching
• Directory services

Standard Edition

• All Core features plus:
• Email integration (IMAP/SMTP)
• Calendar management
• Video meetings (LiveKit)
• Enhanced automation

Enterprise Edition

• All Standard features plus:
• Compliance monitoring (LGPD/GDPR/HIPAA)
• Attendance tracking with LLM assist
• Vector database (Qdrant)
• NVIDIA GPU acceleration
• Advanced monitoring
• gRPC support
• Multi-channel messaging (WhatsApp, Teams, Instagram)
• Human handoff with AI copilot
• CRM automations (collections, scheduling, sales)

QUICK START

# config.csv - Enable all features
name,value
crm-enabled,true
attendant-llm-tips,true
attendant-polish-message,true
attendant-smart-replies,true
attendant-auto-summary,true
attendant-sentiment-analysis,true

# attendant.csv - Configure your team
id,name,channel,preferences,department,aliases
att-001,John Smith,all,sales,commercial,john;johnny
att-002,Maria Santos,whatsapp,support,customer-service,maria

Result: Full hybrid AI+Human support system in minutes.

Full Edition

• All features enabled
• Complete platform capabilities

COMPLIANCE & PRIVACY

General Bots includes built-in compliance templates:

Privacy Rights Center (privacy.gbai)

• Data Access Requests - LGPD Art. 18 / GDPR Art. 15
• Data Rectification - LGPD Art. 18 III / GDPR Art. 16
• Data Erasure - LGPD Art. 18 VI / GDPR Art. 17 (Right to be Forgotten)
• Data Portability - LGPD Art. 18 V / GDPR Art. 20
• Consent Management - LGPD Art. 8 / GDPR Art. 7
• Processing Objection - LGPD Art. 18 IV / GDPR Art. 21

Supported Frameworks

• LGPD (Lei Geral de Proteção de Dados - Brazil)
• GDPR (General Data Protection Regulation - EU)
• HIPAA (Health Insurance Portability and Accountability Act)
• CCPA (California Consumer Privacy Act)
• SOC 2 (Service Organization Control)
• ISO 27001 (Information Security Management)

QUICK START

# Install BotServer
cargo install botserver

# Initialize your deployment
botserver --init my-company

# Start the server
botserver --start

PLATFORM COMPARISON

INTEGRATION CAPABILITIES

LLM Providers

• OpenAI (GPT-5, o3)
• Anthropic (Claude Sonnet 4.5, Opus 4.5)
• Meta (Llama)
• DeepSeek
• Local models via Ollama
• Any OpenAI-compatible API

Communication Channels

• WhatsApp Business
• Microsoft Teams
• Telegram
• Slack
• Instagram
• Web chat
• SMS

Storage Backends

• AWS S3
• MinIO
• Any S3-compatible storage
• Local filesystem

Directory Services

• Built-in user management
• LDAP integration
• Active Directory
• OAuth/OIDC SSO

ABOUT PRAGMATISMO

Pragmatismo develops General Bots as an open-source platform for enterprise AI and automation. Our focus is on delivering practical, production-ready solutions that organizations can deploy and customize to meet their specific needs.

Repository: github.com/GeneralBots/BotServer

License: AGPL-3.0

QUICK START

Ready to see it in action? Skip to the hands-on guide:

⚡ Quick Start: Run Your First Bot in 5 Minutes →

Or continue reading for the full journey:

NEXT STEPS

Chapter 01: Run and Talk →

Introduction to General Bots

⚡ Want to skip ahead? Quick Start → gets you running in 5 minutes.

Build conversational AI bots in minutes, not months. General Bots lets you create intelligent chatbots by writing simple BASIC scripts and dropping in your documents. No complex frameworks, no cloud dependencies, no AI expertise required.

The No Forms Movement

Since 2017, Pragmatismo has championed the No Forms philosophy. The idea is simple but revolutionary:

People should converse, not fill forms.

Traditional software forces users into rigid forms with dropdowns, checkboxes, and validation errors. But humans don’t communicate that way. We talk. We explain. We ask questions.

General Bots was born from this vision: replace forms with conversations.

Before: The Form Experience

┌─────────────────────────────────────────┐
│ Customer Support Form                    │
├─────────────────────────────────────────┤
│ Name: [_______________]                  │
│ Email: [_______________]                 │
│ Department: [Select ▼]                   │
│ Priority: ○ Low ○ Medium ○ High         │
│ Subject: [_______________]               │
│ Description:                             │
│ [                                    ]   │
│ [                                    ]   │
│                                          │
│ Attachments: [Choose File]               │
│                                          │
│ [Submit]                                 │
│                                          │
│ ⚠️ Error: Email format invalid           │
│ ⚠️ Error: Description required           │
└─────────────────────────────────────────┘

Problems:

• Intimidating for users
• Requires learning the interface
• Validation errors frustrate
• No guidance or context
• One-size-fits-all approach

After: The Conversation Experience

Benefits:

• Natural and intuitive
• Guides users step by step
• Adapts to each situation
• No errors, just clarifications
• Feels like talking to a human

Projections, Not Screens

The No Forms philosophy extends beyond chat. In General Bots:

• Visualizations replace dashboards - Data is projected contextually, not displayed in static grids
• Conversations replace menus - Ask for what you need, don’t hunt through options
• AI handles complexity - The system adapts, users don’t configure
• Voice-first design - Everything works without a screen

This is why General Bots focuses on:

1. Conversational interfaces - Chat, voice, messaging
2. Contextual projections - Show relevant info when needed
3. Minimal UI - The less interface, the better
4. AI interpretation - Understand intent, not just input

Quick Example

Want a student enrollment bot? Here’s all you need:

1. Drop your documents in a .gbkb folder:

edu.gbkb/
  enrollment-policy.pdf
  course-catalog.pdf

2. Write a simple tool (optional):

' enrollment.bas
PARAM name, email, course
SAVE "enrollments.csv", name, email, course
TALK "Welcome to " + course + "!"

3. Chat naturally:

User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: Sarah Chen
Bot: Welcome to Computer Science, Sarah!

No form. No UI. Just conversation.

What Makes General Bots Different

Just Run It

./botserver

That’s it. No Kubernetes, no cloud accounts. The bootstrap process installs everything locally in 2-5 minutes. PostgreSQL, vector database, object storage, cache - all configured automatically with secure credentials stored in Vault.

Real BASIC, Real Simple

We brought BASIC back for conversational AI. See our complete keyword reference:

' save-note.bas - A simple tool
PARAM topic, content
SAVE "notes.csv", topic, content, NOW()
TALK "Note saved!"

Four lines. That’s a working tool the AI can call automatically.

Documents = Knowledge

Drop PDFs, Word docs, or text files into .gbkb/ folders. They’re instantly searchable. No preprocessing, no configuration, no pipelines. The bot answers questions from your documents automatically.

Tools = Functions

Create .bas files that the AI discovers and calls automatically. Need to save data? Send emails? Call APIs? Just write a tool. The AI figures out when and how to use it.

Architecture at a Glance

General Bots is a single binary that includes everything:

One process, one port, one command to run. Deploy anywhere - laptop, server, LXC container.

Real-World Use Cases

Customer Support Bot

documents: FAQs, policies, procedures
tools: ticket creation, status lookup
result: 24/7 support that actually helps

Employee Assistant

documents: HR policies, IT guides, company info
tools: leave requests, equipment orders
result: Instant answers, automated workflows

Sales Catalog Bot

documents: product specs, pricing sheets
tools: quote generation, order placement
result: Interactive product discovery

Meeting Assistant

documents: agenda, previous minutes
tools: action item tracking, scheduling
result: AI-powered meeting facilitator

The Package System

Bots are organized as packages - just folders with a naming convention:

my-bot.gbai/                    # Package root
├── my-bot.gbdialog/            # BASIC scripts
│   └── start.bas               # Entry point
├── my-bot.gbkb/                # Knowledge base
│   ├── policies/               # Document collection
│   └── procedures/             # Another collection
└── my-bot.gbot/                # Configuration
    └── config.csv              # Bot settings

Copy the folder to deploy. That’s it. No XML, no JSON schemas, no build process.

Getting Started in 3 Steps

1. Install (2 minutes)

wget https://github.com/GeneralBots/botserver/releases/latest/botserver
chmod +x botserver
./botserver

2. Open Browser

http://localhost:8080

3. Start Chatting

The default bot is ready. Ask it anything. Modify templates/default.gbai/ to customize.

Core Philosophy

1. No Forms - Conversations replace forms everywhere
2. Simplicity First - If it needs documentation, it’s too complex
3. Everything Included - No external dependencies to manage
4. Production Ready - Secure, scalable, enterprise-grade from day one
5. AI Does the Work - Don’t write logic the LLM can handle
6. Projections Over Screens - Show data contextually, not in dashboards

Technical Highlights

• Language: Written in Rust for performance and safety
• Database: PostgreSQL with Diesel ORM
• Cache: Redis-compatible cache for sessions
• Storage: S3-compatible object store (MinIO)
• Vectors: Qdrant for semantic search
• Security: Vault for secrets, Argon2 passwords, AES encryption
• Identity: Zitadel for authentication and MFA
• LLM: OpenAI API, Anthropic, Groq, or local models
• Scripting: Rhai-powered BASIC interpreter

A Brief History

2017 - Pragmatismo launches General Bots with the No Forms manifesto. The vision: conversational interfaces should replace traditional forms in enterprise software.

2018-2020 - Node.js implementation gains traction. Hundreds of bots deployed across banking, healthcare, education, and government sectors in Brazil and beyond.

2021-2023 - Major enterprises adopt General Bots for customer service automation. The platform handles millions of conversations.

2024 - Complete rewrite in Rust for performance, security, and reliability. Version 6.0 introduces the new architecture with integrated services.

Today - General Bots powers conversational AI for organizations worldwide, staying true to the original vision: people should converse, not fill forms.

What’s Next?

• Chapter 01 - Install and run your first bot
• Chapter 02 - Understanding packages
• Chapter 06 - Writing BASIC dialogs
• Templates - Explore example bots

Community

General Bots is open source (AGPL-3.0) developed by Pragmatismo.com.br and contributors worldwide.

• GitHub: https://github.com/GeneralBots/botserver
• Version: 6.1.0
• Status: Production Ready

Ready to build your bot? Turn to Chapter 01 and let’s go!

Built with ❤️ from Brazil since 2017

Chapter 01: Run and Talk

⚡ In a hurry? Jump straight to Quick Start — you’ll be chatting with your bot in 5 minutes.

Get General Bots running and have your first conversation.

What You’ll Achieve

By the end of this chapter, you will:

• Have General Bots running on your machine
• Understand what happens during bootstrap
• Complete your first conversation with a bot
• Know how sessions and channels work

Choose Your Path

The 30-Second Version

./botserver

Open http://localhost:8080. Start chatting. That’s it.

Everything installs automatically on first run—PostgreSQL, storage, cache, and your first bot.

How It Works

Topics in This Chapter

Overview

What General Bots does and how it fits together.

Quick Start

The fastest path from zero to running bot.

Installation

Detailed setup options including LXC containers and production deployment.

First Conversation

Understanding how the bot responds and learns.

Sessions and Channels

How conversations are managed across WhatsApp, Web, Telegram, and more.

Coming From Executive Vision?

If you just read the Executive Vision, here’s what to know:

1. Everything in that feature table? It’s all included in the single botserver binary
2. No configuration needed — Bootstrap detects your system and sets everything up
3. Start simple — Run it, chat with it, then customize

The philosophy is: get running first, understand later.

Prerequisites

• Operating System: Linux, macOS, or Windows (WSL2 recommended)
• Disk Space: ~2GB for botserver-stack
• RAM: 4GB minimum, 8GB recommended
• Ports: 8080 (web), 5432 (database), 9000 (storage)

No Docker required. No cloud accounts. No API keys to start.

Next Step

Quick Start →

Overview

BotServer is an open-source conversational AI platform built in Rust that enables developers to create, deploy, and manage intelligent bots with minimal configuration. This chapter provides a comprehensive introduction to the platform’s architecture, capabilities, and design philosophy.

Core Philosophy

BotServer was designed around five guiding principles that shape every aspect of the platform. Zero Configuration means the system works out of the box with sensible defaults, eliminating lengthy setup processes. The Package-Based approach ensures bots are self-contained in .gbai folders that can be copied and deployed anywhere. BASIC Scripting provides simple, accessible programming for conversation flows that non-programmers can understand and modify. Multi-Channel support means you deploy once and run everywhere across Web, WhatsApp, Teams, and other platforms. Knowledge-First design provides built-in document management and semantic search as core capabilities rather than afterthoughts.

Architecture Overview

BotServer uses a modular architecture organized into three distinct layers that work together to provide a complete conversational AI platform.

Storage Layer

The storage layer handles all data persistence needs. The SQL database stores structured data including users, sessions, and configurations using PostgreSQL with the Diesel ORM. Object storage provides S3-compatible file storage for documents and uploads, typically using MinIO for self-hosted deployments. The high-performance cache layer handles sessions and frequently accessed data using a Redis-compatible store. An optional vector database enables semantic search capabilities for knowledge bases using Qdrant or similar vector stores.

Application Layer

The application layer contains the core bot functionality. The Bot Engine processes conversations and manages state across interactions. The BASIC Interpreter executes conversation scripts written in the General Bots dialect of BASIC. The Package Manager handles bot deployment, lifecycle management, and hot-reloading of changes. Channel Adapters connect to various messaging platforms, translating between platform-specific formats and the internal message representation.

Service Layer

The service layer provides the infrastructure that supports bot operations. The UI Server handles HTTP API requests and WebSocket connections for real-time chat interfaces. The Scheduler executes cron-based tasks for automation and maintenance. LLM Integration connects to language models whether hosted locally or in the cloud. Authentication integrates with directory services for user management and access control.

Key Features

Conversation Management

BotServer provides comprehensive conversation management capabilities. Sessions persist across interactions, maintaining context and state throughout multi-turn dialogs. The context management system tracks conversation history and user information across interactions. Parallel conversation handling allows a single bot instance to manage thousands of simultaneous conversations efficiently.

Knowledge Base System

The knowledge base system turns your documents into searchable, AI-accessible information. Document ingestion supports PDF, TXT, MD, and DOCX formats with automatic text extraction. The indexing pipeline processes documents into searchable chunks stored in the vector database. Semantic search finds relevant information based on meaning rather than just keyword matching. Context injection automatically provides relevant document excerpts to the LLM when generating responses.

BASIC Scripting Language

The BASIC scripting language makes bot development accessible to everyone. The simple syntax allows non-programmers to read and modify conversation flows. Built-in keywords handle common tasks like sending messages, saving data, and calling APIs. The tool integration system lets you create callable functions that the AI can invoke automatically. Event-driven programming support enables reactive bots that respond to schedules, webhooks, and system events.

Multi-Channel Support

Deploy your bot once and reach users across multiple channels. The web chat interface provides an embeddable widget for websites. WhatsApp Business API integration enables customer service on the world’s most popular messaging platform. Microsoft Teams support brings your bot into enterprise collaboration spaces. Email integration allows conversational interactions through traditional email. SMS support via providers enables text message interactions for users without data connectivity.

Enterprise Features

BotServer includes capabilities required for enterprise deployments. Multi-tenancy support allows a single installation to serve multiple organizations with complete isolation. Role-based access control restricts actions based on user roles and permissions. Comprehensive audit logging tracks all actions for compliance and debugging. Horizontal scaling distributes load across multiple instances. High availability configurations ensure continuous operation even during failures.

System Requirements

Minimum Requirements

For development and testing purposes, BotServer runs comfortably on modest hardware. You need at least 4GB of RAM to run all components. A single CPU core is sufficient for light workloads. Reserve at least 10GB of disk space for the application, databases, and documents. The platform runs on Linux, macOS, or Windows operating systems.

Recommended for Production

Production deployments benefit from more substantial resources. Plan for 16GB of RAM to handle concurrent users and large knowledge bases. Two or more CPU cores improve response times under load. Use 100GB of SSD storage for better database and file access performance. Linux servers running Ubuntu or Debian provide the most tested and reliable environment. For local LLM hosting, an NVIDIA RTX 3060 or better GPU with at least 12GB of VRAM enables on-premises inference without cloud API dependencies.

Configuration

Bot configuration uses config.csv files with key-value parameters. Server settings like server_host and server_port control where the UI server listens. LLM configuration through llm-url and llm-model specifies which language model to use. Email settings including email-from and email-server enable outbound email functionality. UI customization parameters like theme-color1, theme-color2, theme-title, and theme-logo brand the interface. Conversation settings such as episodic-memory-history and episodic-memory-threshold tune how context is managed. Refer to the config.csv files in bot packages for the complete list of available parameters.

Bot Package Structure

Each bot is a self-contained .gbai folder that includes everything needed for deployment. The structure organizes different aspects of the bot into subfolders with specific naming conventions.

mybot.gbai/
  mybot.gbot/
    config.csv
  mybot.gbdialog/
    start.bas
    tools/
  mybot.gbkb/
    documents/
  mybot.gbtheme/
    styles/

The .gbot subfolder contains configuration files including the main config.csv. The .gbdialog subfolder holds BASIC scripts with start.bas serving as the entry point and additional scripts providing tools. The .gbkb subfolder stores knowledge base documents organized into topical folders. The optional .gbtheme subfolder contains CSS and assets for UI customization.

Deployment Models

Standalone Server

The standalone deployment model runs a single BotServer instance serving multiple bots. This approach provides the simplest setup with shared resources across bots. Standalone deployment works best for small to medium deployments where isolation between bots is not critical.

LXC Containers

Linux containers provide lightweight virtualization for bot isolation. Each bot or group of bots runs in its own container with dedicated resources. LXC deployment offers easy management through standard container tooling while maintaining lower overhead than full virtual machines.

Embedded Mode

Embedded deployment integrates BotServer into existing applications as a library. This mode provides programmatic control over bot behavior and direct integration with application logic. Custom integrations can use the embedded mode to add conversational capabilities to any Rust application.

Getting Started

Installation begins by downloading and running the BotServer binary. The bootstrap process automatically downloads all required components to the botserver-stack/ directory, including database binaries, the object storage server, cache server, LLM runtime, and other dependencies.

Bot deployment uses object storage buckets. Each bot receives its own bucket for file storage. Bots are deployed to the drive rather than the work folder, which is reserved for internal operations as documented in the gbapp chapter.

After startup, access the UI interface at http://localhost:8080 to interact with your bots and monitor their operation.

Use Cases

Customer Support

Customer support bots automate FAQ responses and ticket handling. Load your support documentation, policies, and procedures into knowledge bases. Create tools for ticket creation and status lookup. The result is 24/7 support that handles common questions automatically while escalating complex issues to human agents.

Internal Tools

Employee assistant bots streamline internal operations. Knowledge bases contain HR policies, IT guides, and company information. Tools enable leave requests, equipment orders, and other common workflows. Employees get instant answers and automated processing for routine requests.

Educational Applications

Educational bots provide interactive learning experiences. Course materials and reference documents become searchable knowledge bases. Tools handle quiz administration, progress tracking, and enrollment. Students receive personalized guidance and immediate feedback.

Healthcare Applications

Healthcare bots assist with patient engagement while maintaining compliance. Appointment scheduling, medication reminders, and symptom checking tools automate routine interactions. Knowledge bases contain patient education materials. All interactions maintain audit trails for regulatory compliance.

Security Features

BotServer implements comprehensive security at every layer. Authentication integrates with directory services for centralized user management. SSL/TLS encryption protects all network communications. Session tokens use cryptographically secure generation and validation. Input sanitization prevents injection attacks across all user inputs. SQL injection prevention uses parameterized queries throughout. XSS protection sanitizes output displayed to users. Rate limiting prevents abuse and denial of service attacks. Audit logging records all significant actions for compliance and forensics.

Monitoring and Operations

Health Checks

Health monitoring endpoints report component status for operational awareness. Database connectivity checks verify the storage layer is operational. Storage availability checks ensure object storage is accessible. Cache performance metrics track response times and hit rates.

Metrics

Operational metrics provide visibility into bot performance. Conversation counts show usage patterns over time. Response time measurements identify performance issues. Error rates highlight problems requiring attention. Resource usage tracking helps capacity planning.

Logging

Structured logging facilitates troubleshooting and analysis. Configurable log levels from ERROR through DEBUG control verbosity. Automatic rotation and archival prevent disk exhaustion. Search and filtering tools help locate specific events in large log files.

Extensibility

Channel Adapters

New messaging channels integrate through the adapter system. WebSocket protocols enable real-time bidirectional communication. REST API integration supports request-response style platforms. Custom protocols can be implemented for specialized messaging systems.

Storage Backends

Storage is abstracted to support multiple backend options. S3-compatible storage works with AWS, MinIO, and other providers. Database adapters could support different SQL databases. Cache providers can be swapped while maintaining the same interface.

Community and Support

Documentation

Comprehensive documentation covers all aspects of the platform. The User Guide walks through common tasks and best practices. The API Reference documents all endpoints and parameters. The BASIC Language Reference details every keyword and syntax rule. The Deployment Guide covers production installation and configuration.

Resources

Example bots in the templates/ directory demonstrate common patterns. Test suites verify functionality and provide usage examples. Migration tools help transition from other platforms to General Bots.

Contributing

General Bots is open source under the AGPL (GNU Affero General Public License). The GitHub repository hosts all development activity. Issue tracking manages bug reports and feature requests. Pull requests from the community are welcome and encouraged.

Summary

BotServer provides a complete platform for building conversational AI applications. The combination of simple BASIC scripting, automatic setup, and enterprise features bridges the gap between simple chatbots and complex AI systems. The focus on packages, minimal configuration, and multi-channel support makes BotServer suitable for both rapid prototyping and production deployments serving millions of users.

Quick Start

Installation in 3 Steps

1. Run BotServer

./botserver

That’s it! No configuration needed.

2. Wait for Bootstrap (2-5 minutes)

You’ll see:

BotServer starting...
Bootstrap: Detecting system...
Installing PostgreSQL...
   Database created
   Schema initialized
Installing Drive...
   Object storage ready
   Buckets created
Installing Cache...
   Cache server running
Creating bots from templates...
   default.gbai deployed
   announcements.gbai deployed
BotServer ready at http://localhost:8080

3. Open Browser

http://localhost:8080

Start chatting with your bot!

What Just Happened?

Bootstrap Flow

The automatic bootstrap process:

1. Detected your OS (Linux/macOS/Windows)
2. Downloaded PostgreSQL database to botserver-stack/
3. Downloaded drive (S3-compatible storage) to botserver-stack/
4. Downloaded cache component to botserver-stack/
5. Generated secure credentials
6. Created database schema
7. Deployed default bots to object storage
8. Started UI server on port 8080

Zero manual configuration required!

Using Existing Services

If you already have PostgreSQL or drive storage running, configure them in config.csv of your bot:

name,value
database-url,postgres://myuser:mypass@myhost:5432/mydb
drive-server,http://my-drive:9000
drive-accesskey,my-access-key
drive-secret,my-secret-key

Step 2: Write a Simple Tool

How Tools Work

Tools are just .bas files. Create enrollment.bas:

' Student enrollment tool
PARAM name, email, course
DESCRIPTION "Processes student enrollment"

SAVE "enrollments.csv", name, email, course, NOW()
TALK "Welcome to " + course + ", " + name + "!"

The LLM automatically discovers this tool and knows when to call it!

Step 3: Add Knowledge Base

Drop documents in a .gbkb/ folder:

mybot.gbai/
  mybot.gbkb/
    docs/
      manual.pdf
      faq.docx
      guide.txt

The bot automatically:

• Indexes documents with vector embeddings
• Answers questions from the content
• Updates when files change

Container Deployment (LXC)

For production isolation, BotServer supports LXC (Linux Containers):

# Create container
lxc-create -n botserver -t download -- -d ubuntu -r jammy -a amd64

# Start and attach
lxc-start -n botserver
lxc-attach -n botserver

# Install BotServer inside container
./botserver

Benefits:

• Process isolation
• Resource control
• Easy management
• Lightweight virtualization

Optional Components

After installation, add more features:

./botserver install email      # Email server
./botserver install directory  # Identity provider
./botserver install llm        # Local LLM server (offline mode)
./botserver install meeting    # Video conferencing

Example Bot Structure

mybot.gbai/
  mybot.gbdialog/          # Dialog scripts
    start.bas            # Entry point (required)
    get-weather.bas      # Tool (auto-discovered)
    send-email.bas       # Tool (auto-discovered)
  mybot.gbkb/              # Knowledge base
    docs/                # Document collection
    faq/                 # FAQ collection
  mybot.gbot/              # Configuration
    config.csv           # Bot parameters
  mybot.gbtheme/           # UI theme (optional)
    custom.css

Deploy new bots by uploading to object storage (creates a new bucket), not the local filesystem. The work/ folder is for internal use only.

Local Development with Auto-Sync

Edit bot files locally and sync automatically to drive storage:

Free S3 Sync Tools:

• Cyberduck - GUI file browser (Windows/Mac/Linux)
• rclone - Command-line sync (All platforms)
• WinSCP - File manager with S3 (Windows)
• S3 Browser - Freeware S3 client (Windows)

Quick Setup with rclone:

# Configure for drive storage
rclone config  # Follow prompts for S3-compatible storage

# Auto-sync local edits to bucket
rclone sync ./mybot.gbai drive:mybot --watch

Now when you:

• Edit .csv → Bot config reloads automatically
• Edit .bas → Scripts compile automatically
• Add docs to .gbkb/ → Knowledge base updates

How It Really Works

You DON’T write complex dialog flows. Instead:

1. Add Documents

mybot.gbkb/
  policies/enrollment-policy.pdf
  catalog/courses.pdf

2. Create Tools (Optional)

' enrollment.bas - just define what it does
PARAM name AS string
PARAM course AS string
SAVE "enrollments.csv", name, course

3. Start Chatting!

User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: John Smith
Bot: [Automatically calls enrollment.bas with collected params]
     Welcome to Computer Science, John Smith!

The LLM handles ALL conversation logic automatically!

Configuration (Optional)

Configure per-bot settings in config.csv:

name,value
server_port,8080
llm-url,http://localhost:8081
episodic-memory-threshold,4
theme-color1,#0d2b55

Troubleshooting

Port 8080 in use?

Edit templates/default.gbai/default.gbot/config.csv:

name,value
server_port,3000

Clean install?

# Remove everything and start fresh
rm -rf botserver-stack/
rm .env
./botserver  # Will regenerate everything

Check component status

./botserver status tables    # PostgreSQL
./botserver status drive     # Drive storage
./botserver status cache     # Cache component

Documentation

• Full Installation Guide - Detailed bootstrap explanation
• Tool Definition - Creating tools
• BASIC Keywords - Language reference
• Package System - Creating bots
• Architecture - How it works

The Magic Formula

Documents + Tools + LLM = Intelligent Bot

What You DON’T Need:

• IF/THEN logic
• Intent detection
• Dialog flow charts
• State machines
• Complex routing

What You DO:

• Drop documents in .gbkb/
• Create simple .bas tools (optional)
• Start chatting!

The LLM understands context, calls tools, searches documents, and maintains conversation naturally.

Philosophy

1. Just Run It - No manual configuration
2. Simple Scripts - BASIC-like language anyone can learn
3. Automatic Discovery - Tools and KBs auto-detected
4. Secure by Default - Credentials auto-generated
5. Production Ready - Built for real-world use

Real Example: Education Bot

1. Add course materials:

   edu.gbkb/
     courses/computer-science.pdf
     policies/enrollment.pdf
   

2. Create enrollment tool:

   ' enrollment.bas
   PARAM name AS string
   PARAM course AS string
   SAVE "enrollments.csv", name, course
   

3. Just chat:

   User: What courses do you offer?
   Bot: [Searches PDFs] We offer Computer Science, Data Science...
   
   User: I want to enroll
   Bot: [Calls enrollment.bas] Let me help you enroll...
   

No programming logic needed - the LLM handles everything!

Installation

BotServer installs itself automatically through the bootstrap process. Just run the binary.

System Requirements

Quick Start

./botserver

The bootstrap process automatically:

1. Detects your system (OS/architecture)
2. Creates botserver-stack/ directory structure
3. Downloads PostgreSQL, Drive, Cache, LLM server
4. Initializes database and storage
5. Deploys default bot
6. Starts all services

First run takes 2-5 minutes.

Using Existing Services

If you have existing infrastructure, configure it in your bot’s config.csv:

name,value
database-url,postgres://myuser:mypass@myhost:5432/mydb
drive-server,http://my-drive:9000
drive-accesskey,my-access-key
drive-secret,my-secret-key

Default Ports

Verify Installation

# Check services
./botserver status

# Test database
psql $DATABASE_URL -c "SELECT version();"

# Test LLM
curl http://localhost:8081/v1/models

# Open UI
open http://localhost:8080

Bot Deployment

Bots deploy to object storage (not local filesystem):

mybot.gbai → creates 'mybot' bucket in drive

The work/ folder is for internal use only.

S3 Sync for Development

Use S3-compatible tools for local editing:

• Cyberduck (GUI)
• rclone (CLI)
• WinSCP (Windows)

# rclone sync example
rclone sync ./mybot.gbai drive:mybot --watch

Edits sync automatically - changes reload without restart.

Memory Optimization

For limited RAM systems:

name,value
llm-server-ctx-size,2048
llm-server-parallel,2

Use quantized models (Q3_K_M, Q4_K_M) for smaller memory footprint.

GPU Setup

For GPU acceleration:

name,value
llm-server-gpu-layers,35

Requires CUDA installed and 12GB+ VRAM.

Deployment Options

Troubleshooting

Next Steps

• Quick Start Guide - Create your first bot
• First Conversation - Test your bot
• Configuration Reference - All settings

First Conversation

After BotServer starts, you can immediately start chatting with your bot. No programming required!

Just Start Talking

Open your browser to http://localhost:8080 and start chatting:

You: Hi!
Bot: Hello! How can I help you today?

You: I want to enroll in a course
Bot: I'll help you with enrollment. Let me collect your information...
     [Bot automatically calls enrollment.bas tool]

You: What documents do you have?
Bot: [Searches .gbkb/ folders and answers from your documents]

That’s it! The LLM handles everything automatically.

How It Works

Drop Documents in .gbkb/

mybot.gbai/
  mybot.gbkb/
    policies/
      enrollment-policy.pdf
      course-catalog.pdf
    faqs/
      student-faq.docx
      payment-guide.txt

The bot automatically indexes all documents, creates vector embeddings, searches when users ask questions, and provides accurate answers from your content.

Create Tools as .bas Files

Create enrollment.bas:

PARAM name AS string          LIKE "John Smith"           DESCRIPTION "Student full name"
PARAM email AS string         LIKE "john@example.com"     DESCRIPTION "Contact email"
PARAM course AS string        LIKE "Computer Science"     DESCRIPTION "Course to enroll in"

DESCRIPTION "Enrollment tool - collects student information and processes enrollment"

SAVE "enrollments.csv", name, email, course, NOW()
TALK "Enrollment complete! Welcome to " + course + ", " + name

The LLM automatically discovers this tool, knows when to call it based on user intent, collects required parameters through natural conversation, and executes the tool when all information is gathered.

The LLM Does Everything Else

You don’t need to write IF/THEN logic, intent detection, dialog flows, state machines, or complex routing. The LLM automatically understands user intent, calls appropriate tools, searches knowledge bases, maintains conversation context, and handles follow-up questions naturally.

Real Example Conversation

With enrollment.bas tool and course documents in .gbkb/:

User: Hello, I'd like to know about your computer science program

Bot: I'd be happy to help you learn about our Computer Science program! 
     Based on our course catalog, the program offers a comprehensive 
     4-year curriculum covering software development, algorithms, 
     databases, and AI. Would you like to know about specific courses 
     or the enrollment process?

User: Yes, I want to enroll

Bot: Great! I'll help you enroll in the Computer Science program. 
     Let me collect your information. What's your full name?

User: John Smith

Bot: Thank you, John. What email address should we use for contact?

User: john.smith@gmail.com

Bot: Perfect! I'm enrolling you in Computer Science now...
     [Executes enrollment.bas tool]
     Enrollment complete! Welcome to Computer Science, John Smith!
     You'll receive a confirmation at john.smith@gmail.com.

User: What are the payment options?

Bot: [Searches payment-guide.txt from .gbkb/]
     According to our payment guide, we offer three options:
     1. Full payment with 10% discount
     2. Monthly installments over 12 months
     3. Semester-based payments
     Which option would you prefer?

The Magic Formula

Documents in .gbkb/ combined with tools in .bas files and the LLM create an intelligent bot. No complex programming needed!

Creating Your First Bot

Start by creating the directory structure for your bot with folders for dialog scripts, knowledge base documents, and bot configuration. Add your documents to the .gbkb/ directory including PDFs, Word documents, text files, and Markdown files. Optionally create tools as .bas files to handle specific actions like processing forms or calling APIs. Then restart BotServer and start chatting. The LLM will answer questions from your documents, call your tools when appropriate, and handle the entire conversation naturally.

mkdir -p mybot.gbai/mybot.gbdialog
mkdir -p mybot.gbai/mybot.gbkb/docs
mkdir -p mybot.gbai/mybot.gbot

Example tool in mybot.gbdialog/my-tool.bas:

PARAM user_name AS string
PARAM request AS string

DESCRIPTION "Handles user requests"

result = CALL "/api/process", user_name, request
TALK "Done! " + result

No Programming Required

Traditional chatbots require complex logic with IF/THEN statements, intent detection, and multi-step dialog management. With BotServer, you simply create the tool with parameters and a description, and the LLM handles all the conversation logic automatically.

Traditional approach (don’t do this):

' Complex multi-step dialog
IF intent = "enrollment" THEN
    TALK "Let me help you enroll. What's your name?"
    HEAR name
    TALK "What's your email?"
    HEAR email
    ' ... lots more code ...
ENDIF

BotServer approach (just create the tool):

' In enrollment.bas - becomes a tool automatically
PARAM name AS string
PARAM email AS string
DESCRIPTION "Collects enrollment information"

SAVE "enrollments.csv", name, email
TALK "Successfully enrolled " + name

What Can You Build?

A customer support bot uses product manuals in .gbkb/ and a create-ticket.bas tool, allowing the LLM to answer questions and create support tickets automatically.

An HR assistant combines the employee handbook in .gbkb/ with a leave-request.bas tool so the LLM can explain policies and process leave requests.

An education platform stores course materials in .gbkb/ and provides enrollment.bas and submit-assignment.bas tools, enabling the LLM to teach content and manage student tasks.

A sales assistant uses product catalogs in .gbkb/ with a create-quote.bas tool, allowing the LLM to answer product questions and generate quotes.

Advanced Features

Dynamic Tool Loading

The LLM can load tools based on context. In start.bas, you simply specify which knowledge bases to use, and tools in .gbdialog/ are auto-discovered. The LLM handles the conversation naturally without explicit HEAR statements.

Multi-Language Support

The LLM handles multiple languages automatically. Users can write in Portuguese, Chinese, or any other language, and the bot responds appropriately in the same language.

Context Awareness

The LLM maintains conversation context throughout the interaction. If a user starts to enroll but then asks about prerequisites, the bot handles the tangent and can return to the enrollment process afterward.

Tips for Success

Organize documents clearly by creating folders for policies, products, FAQs, and tutorials within your .gbkb/ directory. This helps the LLM find relevant information quickly.

Name tools descriptively with names like enrollment.bas, create-ticket.bas, and schedule-meeting.bas. The LLM understands what each tool does from its name and description.

Always add descriptions to tools using the DESCRIPTION keyword. A good description like “This tool processes student enrollment for courses” helps the LLM know when to use the tool.

Let the LLM work without trying to control every aspect of the conversation. Allow it to rephrase responses naturally, handle unexpected questions, and maintain conversation flow on its own.

Next Steps

The Quick Start guide walks you through building your first bot. The Packages chapter explains the package structure in detail. The Tool Definition documentation covers creating sophisticated tools. The Knowledge Base chapter describes document management and indexing.

Remember: Just add documents and tools, and the LLM does the rest!

Sessions and Channels

Every conversation has memory. Sessions are the beating heart of BotServer because they remember who you are, what you have said, and where you left off. Even if you close your browser and come back tomorrow, your conversation continues right where it paused.

What Is a Session?

A session is a persistent conversation container that tracks everything about an ongoing interaction. This includes who is talking through user identity, what has been said through message history, the current state including variables and context, any active tools and knowledge bases, and the bot configuration in use. Think of it like a phone call that can pause and resume anytime without losing the thread of conversation.

How Sessions Start

UI Interface

When a user opens http://localhost:8080, the browser receives a session token in the form of a UUID. This token is stored in localStorage for persistence across page loads. The session itself is created in PostgreSQL for durability and cached for fast access during active conversations.

API Access

Programmatic access to sessions uses the REST API. A POST request to /api/session returns a session ID and secret token. Subsequent requests include the token in the Authorization header as a Bearer token to maintain the session context.

# Get new session
curl -X POST http://localhost:8080/api/session
# Returns: {"session_id": "uuid-here", "token": "secret-token"}

# Use session
curl -H "Authorization: Bearer secret-token" \
     http://localhost:8080/api/chat

Anonymous vs Authenticated

Sessions come in two flavors depending on user identity. Anonymous sessions are auto-created with temporary identities for users who have not logged in. Authenticated sessions link to a user account and maintain permanent history that persists indefinitely.

Session Lifecycle

Sessions move through several states during their existence. Active sessions have no timeout while the user is actively chatting. Idle sessions timeout after 30 minutes by default, though this is configurable. Expired sessions are removed after 7 days for anonymous users, while authenticated sessions never expire automatically.

What Gets Stored

PostgreSQL (Permanent Storage)

The database stores the authoritative session record. The sessions table tracks the unique ID, optional user reference, which bot is being used, creation timestamp, and last activity time. The messages table stores each message with its session reference, role (user, assistant, or system), content, and timestamp. The session_state table holds variables as JSONB data and tracks the current knowledge base and tool context.

Cache (Fast Access)

The cache layer provides rapid access to active session data. Recent messages, current variables, active knowledge bases and tools, and last activity timestamps are all cached under keys prefixed with the session UUID. This caching ensures responsive conversations without constant database queries.

Session Variables

Variables set in BASIC scripts persist across messages automatically. When you store a variable in one message, you can retrieve it in a later message whether that is minutes or days later.

' First message
name = HEAR
SET user_name = name

' Later message (minutes or days later)
GET user_name
TALK "Welcome back, " + user_name

Storage happens automatically through several layers. Writes go to cache immediately for fast access. Every message triggers persistence to PostgreSQL for durability. If the cache misses, data restores automatically from the database.

Context Management

Each session maintains its own isolated context. When one session loads a knowledge base, other sessions remain unaffected. This isolation ensures users see only the information relevant to their conversation.

' Session A
USE KB "policies"
' Only this session sees policies

' Session B (different user)
USE KB "products"  
' This session only sees products

Session contexts include active knowledge bases, loaded tools, LLM configuration overrides, and custom prompts. All of these are scoped to the individual session and do not leak between users.

Multi-Bot Sessions

Different bots create entirely separate sessions. A user visiting /default gets one session connected to the default bot, while visiting /support creates a different session for the support bot. Each bot session is completely independent with its own conversation history, knowledge bases, configuration, and no data sharing between them.

Session Security

Token Generation

Session tokens use cryptographically secure random generation with 256-bit entropy. Tokens are encoded in URL-safe base64 format and are unique per session. This makes tokens effectively impossible to guess or predict.

Token Validation

Every request undergoes validation to ensure security. The system verifies that the token exists, has not expired, matches the claimed session, and that the session is still active. Any failure in this chain rejects the request.

Security Features

Multiple security measures protect sessions. Unguessable tokens prevent session hijacking. New tokens for each session prevent session fixation attacks. Automatic cleanup removes old sessions to prevent accumulation. Rate limiting per session prevents abuse.

Debugging Sessions

View Current Session

Within a BASIC script, you can access session information directly.

session_id = GET "session.id"
TALK "Session: " + session_id

Database Inspection

Direct database queries help debug session issues. You can find all active sessions by querying for recent activity, or view message history for a specific session ordered by timestamp.

Cache Inspection

The cache contents can be examined using the valkey-cli tool. List all session keys or retrieve specific session data like variables or context directly from the cache.

Session Limits

Default limits control resource usage, though all are configurable. Message history keeps the last 50 messages in context. Variable storage allows up to 1MB per session. File uploads accept up to 10MB per file. Each server handles up to 1000 concurrent sessions. Rate limiting restricts each session to 60 messages per minute.

Advanced Features

Session Persistence

Sessions persist across server restarts through the cache and database layers. When users reconnect after a restart, their session state restores automatically. This happens transparently without any action required from users or bot developers.

Session Context Isolation

Each session maintains its own context for knowledge base and tool usage. When you load a knowledge base or enable a tool, the change affects only the current session. Other users in other sessions remain unaffected by your context changes.

' Each session has isolated context
USE KB "docs"
' Only affects current session

How It Works Automatically

Sessions require zero configuration from bot developers. Creation happens automatically on the first request from any client. Storage to database and cache happens automatically as conversations progress. Cleanup runs automatically after sessions expire. Security through token generation happens automatically without any setup. Multi-channel support through automatic adapter selection means the same session infrastructure works across all platforms.

You never need to manage sessions directly. Just use the conversation keywords like TALK, HEAR, SET, and GET. Everything else happens behind the scenes.

Common Patterns

Welcome Back

Personalize greetings by remembering when users last visited. Store the last visit timestamp and check for it on subsequent sessions to customize the welcome message.

last_visit = GET BOT MEMORY "last_visit_" + session_id
IF last_visit THEN
  TALK "Welcome back! Last seen: " + last_visit
ELSE
  TALK "Welcome! First time here?"
END IF
SET BOT MEMORY "last_visit_" + session_id, NOW()

Progressive Disclosure

Reveal more features as users become more engaged by tracking message count and adjusting guidance accordingly.

msg_count = GET "session.message_count"
IF msg_count < 3 THEN
  TALK "I can help with basic questions"
ELSE IF msg_count < 10 THEN
  TALK "Try our advanced features!"
ELSE
  TALK "You're a power user! Check tools menu"
END IF

Multi-User Support

Each user automatically receives their own isolated session. The system handles user separation without any explicit code required. Simply write your dialog logic and trust that each user’s data remains private to their session.

Troubleshooting

If sessions are not persisting, check that PostgreSQL is running and accessible. Verify that the cache server is reachable. Look for disk space issues that might prevent database writes.

If sessions expire too soon, adjust the timeout setting in config.csv. Check that server clocks are synchronized. Monitor for memory pressure that might cause early cache eviction.

If you cannot resume a session, the token might have become invalid through expiration or corruption. The session could have passed its expiration window. Database connection issues can also prevent session restoration.

Write Once, Run Everywhere

The same BASIC script runs across all channels including the UI interface, mobile apps, WhatsApp, Microsoft Teams, email conversations, and voice assistants. Your investment in dialog development pays off everywhere because each channel adapter handles the platform specifics while you focus on conversation logic.

' This same script works everywhere

TALK "Hello! How can I help?"
answer = HEAR
TALK "I understand you need help with: " + answer

Summary

Sessions and channels work together seamlessly in BotServer. Sessions handle state management automatically across any channel, persist data reliably through cache and database layers, and scale efficiently to thousands of concurrent conversations. You focus on writing the conversation flow while the system handles memory management and multi-channel delivery transparently.

Chapter 02: About Packages

How bots are organized in General Bots.

What You’ll Learn

• Package structure (.gbai folders)
• Dialog scripts in BASIC
• Knowledge bases
• Configuration basics
• How packages load

Package Structure

A bot is just a folder ending in .gbai:

my-bot.gbai/
├── my-bot.gbdialog/    # BASIC scripts
├── my-bot.gbkb/        # Documents
├── my-bot.gbot/        # Configuration
├── my-bot.gbtheme/     # Optional styling
└── my-bot.gbdrive/     # Optional storage

Drop the folder in templates/, it loads automatically.

Key Concepts

Dialogs (.gbdialog)

• BASIC scripts that control conversation
• start.bas is optional (but needed to activate tools/KB with USE TOOL/USE KB)
• Simple commands like TALK and HEAR

Knowledge Base (.gbkb)

• Put PDFs and documents in folders
• Automatically becomes searchable
• Bot can answer questions from documents

Configuration (.gbot)

• Single config.csv file
• Simple name,value pairs
• Missing values use defaults

Themes (.gbtheme)

• Optional CSS styling
• Most bots don’t need this

Storage (.gbdrive)

• Links to S3-compatible storage
• For large files and uploads

How It Works

1. Discovery: Finds .gbai folders
2. Loading: Reads all components
3. Indexing: Processes documents
4. Activation: Bot is ready

No build process. No compilation. Just folders and files.

The web UI uses HTMX with server-side rendering - minimal JavaScript, no build process, just HTML templates powered by Rust.

Topics Covered

• .gbai Architecture - Package details
• .gbdialog Dialogs - BASIC scripting
• .gbkb Knowledge Base - Document management
• .gbot Configuration - Settings
• .gbtheme UI Theming - Styling
• .gbdrive File Storage - Storage integration
• Bot Templates - Example bots

.gbai Architecture

A bot is just a folder. The .gbai extension marks a directory as a BotServer package containing everything needed to run a conversational AI bot - scripts, documents, configuration, and themes.

The Dead Simple Structure

my-bot.gbai/                    # This folder = your entire bot
  my-bot.gbdialog/           # BASIC conversation scripts
  my-bot.gbkb/               # Documents for Q&A
  my-bot.gbot/               # Configuration
  my-bot.gbtheme/            # Optional UI customization

That’s it. No manifests, no build files, no dependencies. Copy the folder to deploy.

Visual Architecture

Architecture

How Bootstrap Finds Bots

At startup, BotServer scans templates/ for any folder ending in .gbai:

templates/
  default.gbai/       → Creates bot at /default
  support.gbai/       → Creates bot at /support  
  sales.gbai/         → Creates bot at /sales

Each .gbai becomes a URL endpoint automatically. Zero configuration.

What Goes Where

.gbdialog/ - Your Bot’s Brain

BASIC scripts that control conversation flow:

my-bot.gbdialog/
  start.bas           # Optional - needed to activate tools/KB
  auth.bas            # Login flow
  tools/              # Callable functions
    book-meeting.bas
    check-status.bas
  handlers/           # Event responses
    on-email.bas

Example start.bas (optional, but required for tools/KB):

USE KB "policies"
USE TOOL "book-meeting"
USE TOOL "check-status"
TALK "Hi! I'm your assistant with tools and knowledge ready."

Note: If you don’t need tools or knowledge bases, start.bas is optional. The LLM will handle basic conversations without it.

.gbkb/ - Your Bot’s Knowledge

Documents organized by topic:

my-bot.gbkb/
  policies/           # HR documents
    vacation.pdf
    handbook.docx
  products/           # Product info
    catalog.pdf
    pricing.xlsx
  support/            # Help docs
    faq.md

Each folder becomes a searchable collection. Drop files in, bot learns automatically.

.gbot/ - Your Bot’s Settings

Single config.csv file with key-value pairs:

llm-model,your-preferred-model
temperature,0.7
max-tokens,2000
welcome-message,Hello! How can I help?
session-timeout,1800

No complex JSON or YAML. Just simple CSV that opens in Excel.

.gbtheme/ - Your Bot’s Look (Optional)

Custom web interface styling:

my-bot.gbtheme/
  styles.css          # Custom CSS
  logo.png           # Brand assets
  templates/         # HTML overrides
    chat.html

If missing, uses default theme. Most bots don’t need this.

Real Example: Support Bot

Here’s a complete customer support bot:

support.gbai/
  support.gbdialog/
    start.bas         # Optional, but needed for tools/KB
    tools/
      create-ticket.bas
      check-status.bas
  support.gbkb/
    faqs/
      common-questions.pdf
    guides/
      troubleshooting.docx
  support.gbot/
    config.csv

start.bas (activates tools and knowledge bases):

USE KB "faqs"
USE KB "guides"
USE TOOL "create-ticket"
USE TOOL "check-status"

TALK "Support bot ready. How can I help?"

create-ticket.bas:

PARAM issue, priority
DESCRIPTION "Creates support ticket"

ticket_id = GENERATE_ID()
SAVE "tickets.csv", ticket_id, issue, priority, NOW()
TALK "Ticket #" + ticket_id + " created"

config.csv:

llm-model,your-preferred-model
bot-name,TechSupport
greeting,Welcome to support!

Deployment = Copy Folder

Local Development

cp -r my-bot.gbai/ templates/
./botserver restart
# Visit http://localhost:8080/my-bot

Production Server

scp -r my-bot.gbai/ server:~/botserver/templates/
ssh server "cd botserver && ./botserver restart"

Deployment

LXC Container

lxc file push my-bot.gbai/ container/app/templates/

No build step. No compilation. Just copy files.

Multi-Bot Hosting

One BotServer runs multiple bots:

templates/
  support.gbai/       # support.example.com
  sales.gbai/         # sales.example.com
  internal.gbai/      # internal.example.com
  public.gbai/        # www.example.com

Each bot:

• Gets own URL endpoint
• Has isolated sessions
• Runs independently
• Shares infrastructure

Naming Conventions

Required

• Folder must end with .gbai
• Subfolders must match: botname.gbdialog, botname.gbkb, etc.
• start.bas is optional, but required if you want to use tools or knowledge bases (must USE TOOL and USE KB to activate them)

Recommended

• Use lowercase with hyphens: customer-service.gbai
• Group related bots: support-tier1.gbai, support-tier2.gbai
• Version in folder name if needed: chatbot-v2.gbai

Bootstrap Process

When BotServer starts:

Takes about 5-10 seconds per bot.

UI Architecture

The web interface uses HTMX with server-side rendering - minimal client-side code:

• Askama templates for HTML generation
• HTMX for dynamic updates without JavaScript
• No webpack, no npm build
• Edit and refresh to see changes
• Zero compilation time

Package Size Limits

Default limits (configurable in config.csv):

Example override in your bot’s config.csv:

name,value
package-max-size,209715200
user-file-limit,52428800

Troubleshooting

Bot not appearing?

• Check folder ends with .gbai
• Verify subfolders match bot name
• If using tools/KB, ensure start.bas exists with USE TOOL/USE KB commands

Documents not searchable?

• Ensure files are in .gbkb/ subfolder
• Check file format is supported
• Wait 30 seconds for indexing

Scripts not running?

• Validate BASIC syntax
• Check file has .bas extension
• Review logs for errors

Best Practices

Do’s

• Keep packages under 50MB
• Organize knowledge by topic
• Use clear folder names
• Test locally first

Don’ts

• Don’t nest .gbai folders
• Don’t mix test/prod in same folder
• Don’t hardcode absolute paths
• Don’t store secrets in scripts

Summary

The .gbai architecture keeps bot development simple. No complex frameworks, no build systems, no deployment pipelines. Just organize your files in folders, and BotServer handles the rest. Focus on content and conversation, not configuration.

Next: Learn about .gbdialog Dialogs for writing conversation scripts.

.gbdialog Dialogs

The .gbdialog package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.

What is .gbdialog?

.gbdialog files are written in a specialized BASIC dialect that controls:

• Tool execution and integrations
• LLM prompting and context
• Knowledge base activation
• Session and memory management
• External API calls

Modern Approach: Let the LLM Work

Minimal BASIC Philosophy

Instead of complex logic, use the LLM’s natural understanding:

' Example from announcements.gbai/update-summary.bas
' Generate summaries from documents
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume

' Example from law.gbai/case.bas
' Load context and let LLM answer questions
text = GET "case-" + cod + ".pdf"
text = "Based on this document, answer the person's questions:\n\n" + text
SET CONTEXT text
TALK "Case loaded. You can ask me anything about the case."

Key Components

1. LLM Integration

' LLM is for background processing only - generates content once for all users
' Example: Generate a summary that all users will see
text = GET "document.pdf"
summary = LLM "Summarize this document: " + text
SET BOT MEMORY "daily_summary", summary

' For interactive conversations, use SET CONTEXT and TALK
SET CONTEXT "user_type" AS "premium customer"
TALK "How can I help you today?"

2. Tool Execution

' Define tools with parameters
PARAM name AS string LIKE "John Smith" DESCRIPTION "Customer name"
PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email"

' LLM automatically knows when to call this
SAVE "customers.csv", name, email
TALK "Registration complete!"

3. Knowledge Base Usage

See Knowledge Base documentation for details.

' Activate knowledge base collections
USE KB "products"
USE KB "policies"

' The system AI searches these automatically during conversations
' No LLM command needed - just TALK to the user
TALK "What product information can I help you with?"

Script Structure

Entry Point: start.bas (Optional)

The start.bas file in the .gbdialog folder is optional, but required if you want to activate tools or knowledge bases:

' Optional start script - needed only to activate tools/KB
USE KB "company_docs"
USE TOOL "book-meeting"
USE TOOL "check-status"
TALK "Welcome! How can I assist you today?"

When you need start.bas:

• To activate knowledge bases with USE KB
• To activate tools with USE TOOL
• To set initial context or configuration

When you don’t need start.bas:

• For simple conversational bots
• When the LLM can handle everything without tools/KB
• For basic Q&A without document search

Tool Definitions

Create separate .bas files for each tool. See KB and Tools for more information:

' enrollment.bas - The LLM knows when to use this
PARAM student_name AS string
PARAM course AS string
DESCRIPTION "Enrolls a student in a course"

SAVE "enrollments.csv", student_name, course, NOW()
TALK "Enrolled successfully!"

Best Practices

1. Minimal Logic

' Good - Let system AI handle the conversation naturally
TALK "How can I help you?"
' System AI understands context and responds appropriately

' Avoid - Don't micromanage the flow
' IF user_says_this THEN do_that...

2. Clear Tool Descriptions

DESCRIPTION "This tool books appointments for customers"
' The LLM uses this description to know when to call the tool

3. Context Over Conditions

' Provide context, not rules
SET CONTEXT "business_hours" AS "9AM-5PM weekdays"
TALK "When would you like to schedule?"
' System AI naturally understands to mention hours when relevant

4. Trust the System AI

' The system AI handles conversations naturally
TALK "Hello! I'm here to help."
' System handles greetings, questions, complaints naturally

Common Patterns

Document Summarization - Background Processing (from announcements.gbai)

' Schedule automatic updates - runs in background
SET SCHEDULE "59 * * * *"

' Fetch and summarize documents ONCE for all users
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume  ' Stored for all users

Interactive Case Analysis - User Conversations (from law.gbai)

' Ask for case number - interactive with user
TALK "What is the case number?"
HEAR cod

' Load case document
text = GET "case-" + cod + ".pdf"

IF text THEN 
    ' Set context for system AI to use in conversation
    text = "Based on this document, answer the person's questions:\n\n" + text
    SET CONTEXT text 
    TALK "Case loaded. Ask me anything about it."
ELSE
    TALK "Case not found, please try again."
END IF

Tool Definition Pattern

' Tool parameters (auto-discovered by LLM)
PARAM name AS string
PARAM email AS string
DESCRIPTION "Enrollment tool"

' Tool logic (called when LLM decides)
SAVE "enrollments.csv", name, email
TALK "Successfully enrolled " + name

Multi-Collection Search

USE KB "products"
USE KB "reviews"  
USE KB "specifications"

' System AI searches these collections automatically during conversation
TALK "What would you like to know about our products?"

Advanced Features

Memory Management

See Storage documentation for persistent data options.

SET BOT MEMORY "company_policy", policy_text
' Available across all sessions

retrieved = GET BOT MEMORY "company_policy"

External APIs

See External APIs chapter for integration patterns.

result = GET "https://api.example.com/data"
' For background processing only
summary = LLM "Summarize this data: " + result
SET BOT MEMORY "api_summary", summary

Suggestions

See UI Interface for UI integration.

ADD SUGGESTION "Schedule Meeting" AS "schedule"
ADD SUGGESTION "View Products" AS "products"
' UI shows these as quick actions

Error Handling

The system handles errors gracefully:

• Syntax errors caught at compile time
• Runtime errors logged but don’t crash
• LLM provides fallback responses
• Timeouts prevent infinite operations

Script Execution

Scripts run in a sandboxed environment with:

• Access to session state
• LLM generation capabilities
• Knowledge base search
• Tool execution rights
• External API access (configured)

Migration from Traditional Bots

Old Way (Complex Logic)

' DON'T DO THIS - 1990s style
' IF INSTR(user_input, "order") > 0 THEN
'   IF INSTR(user_input, "status") > 0 THEN
'     TALK "Checking order status..."
'   ELSE IF INSTR(user_input, "new") > 0 THEN
'     TALK "Creating new order..."
'   END IF
' END IF

New Way (System AI Intelligence)

' DO THIS - Let system AI handle conversation naturally
TALK "How can I help you with your order?"
' System AI understands context and intent automatically

The key is to trust the system AI and write less code for more intelligent behavior.

Important Distinction

• LLM Command: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
• Interactive Conversations: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow

See Also

• Chapter 1: Quick Start - Getting started with your first bot
• Chapter 2: Bot Architecture - Understanding all components
• Chapter 3: Knowledge Base - Working with KB collections
• Chapter 5: Keywords Reference - Complete BASIC command reference
• Chapter 9: Conversation Flow - Advanced dialog patterns

.gbkb Knowledge Base

The .gbkb package contains your bot’s domain knowledge - documents that the AI uses to answer questions accurately about your specific organization, products, or services.

What It Does

When you place documents in a .gbkb folder, the system automatically:

1. Extracts text from your files (PDF, DOCX, TXT, MD, HTML, CSV)
2. Creates searchable indexes using vector embeddings
3. Enables semantic search so users can ask questions naturally

This means your bot answers based on YOUR documents, not just general AI knowledge.

Folder Structure

mybot.gbai/
└── mybot.gbkb/
    ├── policies/           ← Collection: "policies"
    │   ├── vacation.pdf
    │   └── handbook.docx
    ├── products/           ← Collection: "products"
    │   ├── catalog.pdf
    │   └── specs.xlsx
    └── support/            ← Collection: "support"
        └── faq.md

Each subfolder becomes a collection you can activate independently.

Using in BASIC Scripts

' Activate collections for this conversation
USE KB "policies"
USE KB "products"

' Now the AI automatically searches these when answering
TALK "How can I help you today?"

' Later, clear when done
CLEAR KB "policies"

Supported File Types

Key Points

• Automatic indexing - Just drop files in folders
• Semantic search - Users don’t need exact keywords
• Multiple collections - Organize by topic, activate as needed
• No code required - The AI handles search automatically

Learn More

• Chapter 03: Knowledge Base System - Technical deep-dive on indexing, vectors, and search
• USE KB Keyword - Complete keyword reference
• CLEAR KB Keyword - Managing active collections

.gbot Bot Configuration

The .gbot package serves as the configuration center for your bot, containing the settings that define how the bot behaves, which AI models it uses, and how it interacts with users. This chapter explains the configuration system and guides you through the available options.

Understanding Bot Configuration

Every bot in General Bots requires configuration to operate effectively. The .gbot folder within your bot package holds these settings, primarily through a config.csv file that uses simple key-value pairs. This approach makes configuration accessible to anyone comfortable with spreadsheet applications while remaining powerful enough for complex deployments.

The configuration system influences several aspects of bot behavior. Bot identity settings control how the bot presents itself to users. LLM configuration determines which language model powers the bot’s intelligence and how it generates responses. Context management settings affect how the bot maintains conversation history and retrieves relevant information. Integration parameters connect the bot to external services and APIs.

The config.csv File

Configuration lives in a straightforward CSV format with two columns: key and value. This design choice prioritizes accessibility—you can edit configuration in any text editor or spreadsheet application without learning complex syntax. Each row represents a single setting, making it easy to scan and modify.

The file supports various data types implicitly. Text values are stored as-is, numbers are parsed when needed, and boolean values typically use “true” and “false” strings. The system handles type conversion automatically when reading configuration, so you rarely need to worry about explicit typing.

Bot Identity Configuration

Identity settings establish how your bot presents itself during conversations. The bot_name parameter provides the display name users see when interacting with the bot. A descriptive bot_description helps users understand the bot’s purpose and capabilities. Version tracking through the version parameter supports deployment management and debugging.

These identity settings matter because they shape user expectations. A bot named “Legal Document Assistant” with an appropriate description sets different expectations than a generic “Helper Bot.” Clear identity configuration improves user experience by establishing context before conversations begin.

Language Model Settings

LLM configuration represents perhaps the most important settings in your bot. The llm_provider parameter specifies which AI service powers your bot, supporting options like OpenAI, Azure OpenAI, or local model servers. The llm_model parameter identifies the specific model to use, such as GPT-5, Claude Sonnet 4.5, or a local GGUF model.

Response characteristics are controlled through several parameters. The temperature setting affects response creativity, with lower values producing more focused and deterministic outputs while higher values allow more varied and creative responses. The max_tokens parameter limits response length, preventing runaway generation and managing costs for cloud-based providers.

The system_prompt parameter provides instructions that shape the bot’s personality and behavior throughout conversations. This prompt is prepended to every interaction, giving the model consistent guidance about how to respond, what tone to use, and what boundaries to respect.

Context Management

Context settings control how the bot maintains awareness of conversation history and relevant information. The context_window parameter determines how many previous messages remain visible to the model during each interaction. Larger windows provide better continuity but consume more tokens.

The context_provider setting influences how context is assembled and presented to the model. Different providers may apply various strategies for selecting and formatting context, optimizing for different use cases.

Memory functionality, controlled by the memory_enabled setting, allows bots to retain information across sessions. When enabled, bots can remember user preferences, previous interactions, and other persistent data that improves personalization.

Configuration Loading and Precedence

The system assembles configuration from multiple sources, applying them in a specific order that allows flexible overrides. Default values provide baseline behavior when no explicit configuration exists. Settings in your .gbot/config.csv file override these defaults for your specific bot.

Environment variables can override config.csv settings, useful for deployment scenarios where configuration varies between environments. Database configuration provides another override layer, supporting runtime configuration changes that persist across restarts. Finally, runtime API calls can temporarily adjust settings without permanent changes.

This precedence system enables sophisticated deployment patterns. Development environments might use local configuration files while production deployments pull settings from environment variables or databases. The same bot package can behave differently across environments without modification.

Dynamic Configuration with Bot Memory

Beyond static configuration, bots can store and retrieve dynamic settings using bot memory. The SET BOT MEMORY keyword stores values that persist across all sessions, effectively creating runtime configuration that can be modified through bot scripts.

This capability supports scenarios where configuration needs to adapt based on usage patterns, administrative decisions, or external inputs. A bot might store preferred response styles, accumulated statistics, or cached data that influences its behavior.

Best Practices

Effective configuration follows several principles. Keep identity settings clear and accurate—users trust bots more when their purpose is evident. Choose LLM settings that balance capability with cost and latency requirements. Set appropriate context windows that provide continuity without excessive token consumption.

Document non-obvious configuration choices, either in comments within config.csv or in accompanying documentation. This practice helps future maintainers understand why settings were chosen and whether they should be adjusted.

Test configuration changes in development environments before deploying to production. Some settings interact in non-obvious ways, and testing catches issues before they affect users.

Summary

The .gbot configuration system provides comprehensive control over bot behavior through accessible CSV files augmented by environment variables, database settings, and runtime adjustments. Understanding these configuration options and their precedence helps you build bots that behave predictably across different deployment scenarios while remaining adaptable to changing requirements.

.gbtheme UI Theming

The .gbtheme package provides visual customization for your bot’s web interface through straightforward CSS-based theming. This approach prioritizes simplicity—you create CSS files that override default styles, without needing complex build tools, template engines, or JavaScript frameworks.

The Philosophy of Simple Theming

Many theming systems require elaborate toolchains, preprocessors, and build processes that create barriers for non-developers who want to customize their bot’s appearance. General Bots takes a different approach by using plain CSS files that any web designer can create and modify.

This simplicity doesn’t sacrifice capability. CSS custom properties (variables) provide the flexibility to change colors, typography, spacing, and other visual characteristics throughout the interface by modifying a few central values. The bot’s default interface handles all the complex layout and functionality concerns, leaving themes to focus purely on appearance.

Theme Structure

A theme consists of one or more CSS files placed in the .gbtheme folder within your bot package. The simplest theme might be a single default.css file containing variable overrides. More complex setups might include multiple theme files for different contexts—a dark theme for evening use, a high-contrast theme for accessibility, or seasonal themes for special occasions.

The system automatically loads the default theme on startup, and scripts can switch between available themes at runtime based on user preferences, time of day, or any other logic you implement.

CSS Variables and Customization

The bot interface defines a set of CSS custom properties that control fundamental visual characteristics. By overriding these properties in your theme file, you can transform the interface’s appearance with minimal code.

The primary-color variable establishes your main brand color, used for headers, buttons, and other prominent elements. The secondary-color provides accent coloring for highlights and interactive elements. Background and text-color control the basic page appearance and readability.

Typography settings including font-family let you match your organization’s brand standards. Structural properties like border-radius affect the overall feel—sharp corners suggest professionalism while rounded corners feel friendlier. Spacing controls help maintain consistent visual rhythm throughout the interface.

These variables cascade through the interface components, meaning a single change propagates everywhere that property is used. This approach makes comprehensive theming achievable with just a handful of variable overrides.

Creating Effective Themes

Building a theme starts with understanding your visual goals. Corporate deployments often need to match existing brand guidelines, requiring specific colors, fonts, and visual treatments. Consumer-facing bots might prioritize approachability and visual appeal. Internal tools might emphasize clarity and efficiency over aesthetics.

A minimal theme might override only the primary and secondary colors to match brand standards while accepting defaults for everything else. This approach gets results quickly with minimal effort. As needs grow, you can progressively add more customization.

When creating dark themes, remember to adjust not just the background color but also text colors, borders, shadows, and any other elements that assume a light background. Contrast matters for readability—test your themes with actual content to ensure text remains legible.

Accessibility considerations should inform theme design. Ensure sufficient contrast ratios between text and backgrounds, avoid relying solely on color to convey information, and test with various visual impairments in mind.

Dynamic Theme Switching

Bots can change themes at runtime through the CHANGE THEME keyword in BASIC scripts. This capability enables several useful patterns.

User preference systems let visitors choose their preferred theme, with the selection stored in user memory for future visits. Time-based switching can apply dark themes during evening hours automatically. Contextual theming might use different visual treatments for different conversation modes or topics.

Theme switching happens instantly without page reloads, providing smooth transitions that maintain conversation flow.

Configuration Integration

Theme settings can also be specified in the bot’s config.csv file, providing default values that themes can override. The theme parameter specifies which theme file to load by default. The theme-color1 and theme-color2 parameters provide primary and secondary colors that the interface uses when no theme file specifies otherwise.

These configuration values serve as fallbacks—CSS files in the .gbtheme folder take precedence when they define the same properties. This layering allows simple color customization through configuration while supporting full CSS theming for more sophisticated needs.

No Build Process Required

Unlike many modern web development workflows, .gbtheme requires no build tools, preprocessors, or compilation steps. You write CSS files, place them in the appropriate folder, and they take effect. Changes appear immediately through hot reloading, making iterative design work fast and responsive.

This simplicity means designers without development environment setup can contribute themes. Anyone who can write CSS can customize the interface, lowering barriers to visual customization.

Migrating from Complex Systems

Organizations moving from platforms with complex theming systems can extract their essential visual parameters and recreate them as CSS variable overrides. The process typically involves identifying brand colors and typography from the existing theme, mapping those values to General Bots CSS variables, testing the result against the interface, and iteratively refining until the appearance matches expectations.

Much of the complexity in traditional theming systems exists to handle layout and functionality concerns that General Bots manages through its default interface. By focusing themes purely on visual styling, the migration process becomes much simpler.

Best Practices

Effective theming follows several principles. Keep theme files focused and minimal—override only what you need to change rather than redefining everything. Start with a single default.css file and add complexity only as requirements demand.

Test themes across different devices and screen sizes to ensure they work well everywhere. Pay attention to interactive states like hover, focus, and active to ensure the interface remains usable and visually coherent.

Document theme choices, especially when values differ from brand guidelines for technical reasons. Future maintainers will appreciate understanding why specific decisions were made.

Maintain consistency within themes—if you override one color, consider whether related elements need adjustment to maintain visual harmony.

Summary

The .gbtheme system demonstrates that powerful customization doesn’t require complex tooling. Through CSS variables and standard stylesheets, you can transform the bot interface’s appearance while the platform handles the underlying complexity. This approach respects the skills of designers and developers alike, enabling visual customization without artificial barriers.

.gbdrive File Storage

The .gbdrive system provides centralized file storage for all bot packages, leveraging S3-compatible object storage to deliver reliable, scalable storage infrastructure. This chapter explains how file storage works, how files are organized, and how to interact with stored content.

Understanding File Storage in General Bots

Every bot requires storage for its various components—scripts, documents, configuration files, user uploads, and generated content. Rather than managing files across disparate locations, General Bots consolidates storage through the .gbdrive system, which provides a consistent interface regardless of the underlying storage backend.

The storage system builds on S3-compatible object storage, meaning it works with self-hosted solutions like MinIO as well as cloud providers like AWS S3, Backblaze B2, or DigitalOcean Spaces. This flexibility allows deployments to choose storage solutions that match their requirements for cost, performance, and data residency.

Beyond simple file storage, the system provides versioning capabilities, access control, automatic synchronization, and integration with other bot components like knowledge bases and themes.

Storage Organization

Files are organized using a bucket-per-bot structure that keeps each bot’s content isolated and manageable. Within a bot’s storage bucket, the familiar package structure appears: .gbdialog for scripts, .gbkb for knowledge base collections, .gbot for configuration, and .gbtheme for interface customization.

Additionally, each bot has space for user-uploaded files, generated content, and other runtime data. This organization mirrors the logical structure you work with during development, making it intuitive to understand where files reside and how they relate to bot functionality.

The system maintains this structure automatically when bots are deployed or updated, ensuring that the storage state reflects the current bot configuration without manual intervention.

.gbusers - Per-User Storage

The .gbusers folder within .gbdrive provides isolated storage space for each user interacting with the bot. This enables personalized document storage, user-specific settings, and application data that persists across sessions.

User Folder Structure

User folders are identified by the user’s email address or phone number:

mybot.gbai/
  mybot.gbdrive/
    users/
      john@example.com/           # User identified by email
        papers/
          current/                # Active/working documents
            untitled-1.md
            meeting-notes.md
          named/                  # Saved/named documents
            quarterly-report/
              document.md
              attachments/
            project-proposal/
              document.md
        uploads/                  # User file uploads
        exports/                  # Generated exports (PDF, DOCX, etc.)
        settings/                 # User preferences
          preferences.json
      +5511999887766/             # User identified by phone number
        papers/
          current/
          named/
        uploads/

User Identifier Format

Users are identified by their primary contact method:

• Email: john@example.com, maria@company.com.br
• Phone: +5511999887766, +1234567890 (E.164 format)

The identifier is sanitized for filesystem compatibility while remaining human-readable.

Paper Document Storage

The Paper application stores user documents in the papers/ directory:

• papers/current/: Working documents that are actively being edited. These may be auto-saved drafts or recently accessed files.
• papers/named/: Documents that have been explicitly saved with a name. Each named document gets its own folder to support attachments and metadata.

Example document structure:

papers/
  current/
    untitled-1.md           # Auto-saved draft
    untitled-2.md           # Another working document
  named/
    meeting-notes-2024/
      document.md           # The main document content
      metadata.json         # Title, created_at, updated_at, etc.
      attachments/          # Embedded images or files
        image-001.png
    research-paper/
      document.md
      metadata.json

Accessing User Storage from BASIC

BASIC scripts can access user storage using the USER DRIVE keyword:

' Read a user's document
content = READ USER DRIVE "papers/current/notes.md"

' Write to user's storage
SAVE USER DRIVE "papers/named/report/document.md", report_content

' List user's papers
papers = LIST USER DRIVE "papers/named/"

' Delete a user document
DELETE USER DRIVE "papers/current/draft.md"

User Storage API

The REST API provides endpoints for user storage operations:

GET  /api/drive/user/list?path=papers/current/
POST /api/drive/user/read
     { "path": "papers/named/report/document.md" }
POST /api/drive/user/write
     { "path": "papers/current/notes.md", "content": "..." }
POST /api/drive/user/delete
     { "path": "papers/current/draft.md" }

All user storage API calls require authentication and automatically scope operations to the authenticated user’s folder.

Storage Quotas

Each user has configurable storage limits:

Configure in config.csv:

user-storage-quota,104857600
user-file-limit,5242880
user-file-count,500

Working with Files

File operations in General Bots happen through several interfaces depending on your needs. The BASIC scripting language provides keywords for reading file content directly into scripts, enabling bots to process documents, load data, or access configuration dynamically.

Files can also be managed through the administrative API for bulk operations, migrations, or integration with external systems. The web interface provides user-facing upload and download capabilities where appropriate.

When files change in storage, the system detects modifications and triggers appropriate responses. Script changes cause recompilation, document changes trigger knowledge base reindexing, and configuration changes reload bot settings. This hot-reloading capability accelerates development and enables runtime updates without service interruption.

Integration with Bot Components

The storage system integrates deeply with other bot components, serving as the foundation for several capabilities.

Knowledge bases draw their source documents from storage, with the indexing system monitoring for changes and updating embeddings accordingly. When you add a document to a .gbkb folder, it automatically becomes part of the bot’s searchable knowledge.

Theme assets including CSS files and images are served from storage, with appropriate caching to ensure good performance. Changes to theme files take effect quickly without requiring restarts.

Tool scripts in .gbdialog folders are loaded from storage, parsed, and made available for execution. The compilation system tracks dependencies and rebuilds as needed when source files change.

Paper Application Integration

The Paper document editor automatically saves to the user’s .gbusers folder:

1. Auto-save: Every 30 seconds, working documents are saved to papers/current/
2. Explicit save: When users click “Save”, documents move to papers/named/{document-name}/
3. Export: Generated exports (PDF, DOCX) are saved to exports/ and offered for download
4. AI-generated content: AI responses can be inserted into documents and saved automatically

Access Control

Different files require different access levels, and the storage system enforces appropriate controls:

• Public files: Accessible without authentication, suitable for shared resources
• Authenticated access: Requires valid user credentials, protects user-specific content
• User-scoped access: Users can only access their own .gbusers folder content
• Bot-internal files: Accessible only to the bot system itself
• Administrative files: Require elevated privileges to access or modify

User storage in .gbusers is strictly isolated—users cannot access other users’ folders through any API or BASIC keyword.

Storage Backend Options

The storage system supports multiple backends to accommodate different deployment scenarios. The default configuration uses self-hosted S3-compatible object storage, providing full control over where data resides. Any S3-compatible service works as an alternative, including major cloud providers.

For development and testing, local filesystem storage offers simplicity and easy inspection of files. Production deployments might use hybrid configurations with multiple backends providing redundancy or geographic distribution.

Backend selection happens through configuration, and the rest of the system interacts with storage through a consistent interface regardless of which backend is active. This abstraction allows deployments to change storage strategies without modifying bot code.

Directory Structure Reference

Complete .gbdrive structure with all components:

mybot.gbai/
  mybot.gbdrive/
    dialogs/              # Compiled dialog scripts cache
    kb/                   # Knowledge base index data
    cache/                # Temporary cache files
    exports/              # Bot-level exports
    uploads/              # Bot-level uploads
    users/                # Per-user storage (.gbusers)
      user@email.com/
        papers/
          current/        # Working documents
          named/          # Saved documents
        uploads/          # User uploads
        exports/          # User exports
        settings/         # User preferences
      +1234567890/
        papers/
        uploads/
        exports/
        settings/

Summary

The .gbdrive storage system provides the foundation for all file-based operations in General Bots. Through S3-compatible object storage, organized bucket structures, automatic synchronization, and deep integration with other components, it delivers reliable file management that supports both development workflows and production operation.

The .gbusers folder structure enables personalized storage for each user, supporting applications like Paper that require persistent document storage. By organizing user data under their email or phone identifier, the system maintains clear separation while enabling powerful per-user features.

Understanding how storage works helps you organize bot content effectively and leverage the automatic capabilities the system provides.

Bot Templates

BotServer includes pre-built bot templates for various use cases. Each template is a complete .gbai package ready to deploy.

Complete Template List (Flat Reference)

Templates by Category

Core Templates

HR & People

IT & Support

CRM & Sales

Finance & Accounting

Operations

Template Structure

All templates follow this standard directory layout:

template-name.gbai/
  template-name.gbdialog/    # BASIC dialog scripts
    start.bas                # Entry point (required)
    *.bas                    # Tool scripts (auto-discovered)
    *-jobs.bas               # Scheduled jobs
  template-name.gbkb/        # Knowledge base collections
    collection1/             # Documents for USE KB "collection1"
  template-name.gbdrive/     # File storage (not KB)
    uploads/                 # User uploaded files
    exports/                 # Generated files
  template-name.gbot/        # Configuration
    config.csv               # Bot parameters
  template-name.gbtheme/     # UI theme (optional)
    default.css              # Theme CSS

Quick Start Guide

1. Choose a Template

Select based on your needs:

• Simple chat: Use default.gbai
• Business app: Choose crm.gbai, bi.gbai, or erp.gbai
• AI features: Pick ai-search.gbai or llm-tools.gbai
• Communication: Select broadcast.gbai or whatsapp.gbai

2. Deploy the Template

# Templates are auto-deployed during bootstrap
# Access at: http://localhost:8080/template-name

3. Customize Configuration

Edit template-name.gbot/config.csv:

name,value
bot-name,My Custom Bot
welcome-message,Hello! How can I help?
llm-model,model.gguf
temperature,0.7

4. Add Knowledge Base

Place documents in .gbkb folders:

• Each folder becomes a collection
• Use USE KB "folder-name" in scripts
• Documents are automatically indexed

5. Create Tools

Add .bas files to .gbdialog:

• Each file becomes a tool
• Auto-discovered by the system
• Called automatically by LLM when needed

Required Files for Each Template

start.bas (Required)

' Template Name - Start Script

' Setup Tools
ADD TOOL "tool-name-1"
ADD TOOL "tool-name-2"

' Setup Knowledge Base
USE KB "template-name.gbkb"

' Set Context
SET CONTEXT "context name" AS "You are a [role]. You help with [tasks]."

' Setup Suggestions
CLEAR SUGGESTIONS
ADD SUGGESTION "action1" AS "Display text 1"
ADD SUGGESTION "action2" AS "Display text 2"

' Welcome Message
BEGIN TALK
    **Template Title**
    
    Welcome message here.
    
    **What I can help with:**
    • Feature 1
    • Feature 2
END TALK

BEGIN SYSTEM PROMPT
    Detailed instructions for the AI...
END SYSTEM PROMPT

Tool File Template

PARAM paramname AS STRING LIKE "example" DESCRIPTION "What this parameter is"
PARAM optionalparam AS STRING LIKE "default" DESCRIPTION "Optional parameter"

DESCRIPTION "What this tool does. Called when user wants to [action]."

' Business logic
let result = "processed"

' Save data (field names = variable names)
SAVE "table.csv", paramname, optionalparam, result

' Store in memory
SET BOT MEMORY "last_item", result

' Response
TALK "✅ Action completed successfully!"

config.csv Template

name,value
episodic-memory-history,2
episodic-memory-threshold,4
theme-color1,#1565C0
theme-color2,#E3F2FD
theme-logo,https://pragmatismo.com.br/icons/general-bots.svg
theme-title,Template Name - General Bots

Syntax Rules for Templates

DO ✅

' Variable names (no underscores in names)
let ticketnumber = "TKT001"
let useremail = "user@example.com"

' SAVE with field names = variable names
SAVE "table.csv", ticketnumber, useremail, status

' Keywords with spaces
SET BOT MEMORY "last_ticket", ticketnumber
SET CONTEXT "name" AS "description"
ADD SUGGESTION "key" AS "Display text"
CLEAR SUGGESTIONS
USE KB "myknowledge"
USE TOOL "mytool"

' GET BOT MEMORY as function
let lastticket = GET BOT MEMORY("last_ticket")

DON’T ❌

' NO: Complex object operations
SET object.field = value  ' WRONG
SAVE "table", object.id, object  ' WRONG

Creating Custom Templates

To create your own template:

1. Copy template.gbai as starting point
2. Define clear purpose - one template, one job
3. Structure folders properly:
   • .gbdialog for scripts
   • .gbkb for knowledge collections
   • .gbdrive for general files
   • .gbot for configuration
4. Include examples - sample data and dialogs
5. Test thoroughly - verify all features

Best Practices

Template Selection

1. Start small: Begin with default.gbai
2. Match use case: Choose aligned templates
3. Combine features: Mix templates as needed
4. Keep originals: Copy before modifying

Customization Strategy

Minimal BASIC Approach

Instead of complex dialog flows, use simple LLM calls:

' Let system AI handle conversations naturally
TALK "How can I assist you?"
' System AI understands and responds appropriately

Tool Creation

Only create .bas files for specific actions:

• API calls
• Database operations
• File processing
• Calculations

Knowledge Base Organization

• One folder per topic/collection
• Name folders clearly
• Keep documents updated
• Index automatically

Performance Tips

• Remove unused template files
• Index only necessary documents
• Configure appropriate cache settings
• Monitor resource usage

Support Resources

• README files in each template folder
• Example configurations included
• Sample knowledge bases provided
• Community forums for discussions

Template Samples & Conversations

Ready-to-use bots for common business needs

See real conversations and learn how each template works

How to Use Templates

1. Go to Sources app
2. Click + New Bot
3. Select From Template
4. Choose the template you want
5. Click Create

Your bot is ready to use immediately!

Customer Support (CRM Template)

Best for: Handling customer inquiries, tracking issues, managing contacts

Sample Conversation

User: I need help with my order

Bot:  I'd be happy to help with your order! 
      What's your order number?

User: ORD-12345

Bot:  Found it! Order #ORD-12345
      
      📦 Status: Shipped
      📅 Shipped: May 14, 2025
      🚚 Carrier: FedEx
      📍 Tracking: 7891234567890
      
      Expected delivery: May 17, 2025
      
      Is there something specific about this order?

User: I want to return it

Bot:  I can help you start a return for Order #ORD-12345.
      
      📋 Return Policy:
      • Returns accepted within 30 days
      • Item must be unused
      • Original packaging required
      
      Would you like me to create a return request?

User: Yes

Bot:  ✅ Return Request Created!
      
      Return #: RET-5678
      
      Next steps:
      1. Print the return label (sent to your email)
      2. Pack the item securely
      3. Drop off at any FedEx location
      
      Refund will process within 5-7 business days 
      after we receive the item.
      
      Anything else I can help with?

What It Can Do

• Look up orders by number or customer email
• Check shipping status
• Create return requests
• Log customer interactions
• Track support tickets

FAQ Bot (AI Search Template)

Best for: Answering common questions from your documents

Sample Conversation

User: What's your refund policy?

Bot:  Based on our policies:
      
      **Refund Policy**
      
      • Full refund within 30 days of purchase
      • Items must be unused and in original packaging
      • Refunds processed to original payment method
      • Processing time: 5-7 business days
      
      For items over 30 days old, store credit is available.
      
      📄 Source: Company Policies Handbook, Page 12

User: How do I contact support?

Bot:  You can reach our support team through:
      
      📧 Email: support@company.com
      📞 Phone: 1-800-555-0123 (Mon-Fri, 9am-5pm)
      💬 Chat: You're using it right now!
      
      Average response time:
      • Chat: Immediate
      • Email: Within 24 hours
      • Phone: Under 5 minutes wait
      
      📄 Source: Contact Information Page

User: Do you ship internationally?

Bot:  Yes! We ship to over 50 countries.
      
      **International Shipping:**
      • Standard: 10-15 business days ($15)
      • Express: 5-7 business days ($35)
      
      **Note:** Import duties and taxes may apply 
      depending on your country.
      
      Countries we ship to include: Canada, UK, 
      Australia, Germany, France, Japan, and more.
      
      📄 Source: Shipping FAQ Document

Setup Tips

1. Upload your FAQ documents to the knowledge base
2. Include policy documents, product guides, help articles
3. The bot automatically learns from your files

Appointment Booking (Calendar Template)

Best for: Scheduling meetings, consultations, appointments

Sample Conversation

User: I want to book an appointment

Bot:  I'll help you schedule an appointment!
      
      What type of appointment do you need?
      
      1. 📋 Consultation (30 min)
      2. 🔧 Service Visit (1 hour)
      3. 📞 Phone Call (15 min)

User: Consultation

Bot:  Great! A 30-minute consultation.
      
      Here are available times this week:
      
      📅 Tuesday, May 20
         • 10:00 AM
         • 2:00 PM
         • 4:00 PM
      
      📅 Wednesday, May 21
         • 9:00 AM
         • 11:00 AM
         • 3:00 PM
      
      Which works best for you?

User: Tuesday at 2pm

Bot:  Perfect! Let me confirm your details.
      
      What's your name?

User: John Smith

Bot:  And your email address?

User: john@email.com

Bot:  ✅ Appointment Confirmed!
      
      📋 Consultation
      👤 John Smith
      📅 Tuesday, May 20, 2025
      🕐 2:00 PM (30 minutes)
      
      A confirmation email has been sent to 
      john@email.com with calendar invite.
      
      Need to reschedule? Just ask!

What It Can Do

• Show available time slots
• Book appointments
• Send confirmation emails
• Send reminders before appointments
• Allow rescheduling and cancellation

HR Assistant (Employee Template)

Best for: Employee self-service, HR questions, leave requests

Sample Conversation

User: How many vacation days do I have?

Bot:  Let me check your balance, John.
      
      📊 Your Time Off Balance:
      
      Vacation Days
      ├── Available: 12 days
      ├── Used: 3 days
      └── Pending: 0 days
      
      Sick Days
      ├── Available: 8 days
      └── Used: 2 days
      
      Your vacation resets on January 1, 2026.
      
      Would you like to request time off?

User: Yes, I need next Friday off

Bot:  I'll create a time off request for you.
      
      📅 Requesting: Friday, May 23, 2025
      📋 Type: Vacation (1 day)
      
      Reason for time off? (optional)

User: Personal appointment

Bot:  ✅ Time Off Request Submitted!
      
      📋 Request #PTO-2025-0142
      📅 Date: May 23, 2025 (1 day)
      📝 Reason: Personal appointment
      👤 Approver: Sarah Johnson (your manager)
      
      You'll receive an email when it's approved.
      
      Current status: ⏳ Pending Approval

User: What holidays do we have this year?

Bot:  📅 Company Holidays 2025:
      
      ✓ New Year's Day - Jan 1 (past)
      ✓ Memorial Day - May 26
      ✓ Independence Day - July 4
      ✓ Labor Day - Sep 1
      ✓ Thanksgiving - Nov 27-28
      ✓ Christmas - Dec 25-26
      
      Total: 8 paid holidays
      
      Note: If a holiday falls on a weekend, 
      it's observed on the nearest weekday.

What It Can Do

• Check PTO balances
• Submit time off requests
• Look up company holidays
• Answer HR policy questions
• Find employee directory info

Sales Lead Capture

Best for: Qualifying leads, collecting contact info, scheduling demos

Sample Conversation

User: I'm interested in your product

Bot:  Great! I'd love to learn more about what you're 
      looking for.
      
      What's your name?

User: Maria Garcia

Bot:  Nice to meet you, Maria! 
      
      What company are you with?

User: Acme Corp

Bot:  Acme Corp - got it!
      
      What's your role there?

User: Marketing Director

Bot:  Perfect! And what's the best email to reach you?

User: maria@acmecorp.com

Bot:  Thanks Maria! One last question:
      
      What's your biggest challenge right now?
      
      1. 📈 Growing leads
      2. ⏱️ Saving time on manual tasks
      3. 📊 Better reporting
      4. 🔗 Integrating tools
      5. Other

User: Saving time

Bot:  That's exactly what we help with!
      
      ✅ I've saved your information:
      
      👤 Maria Garcia
      🏢 Acme Corp (Marketing Director)
      📧 maria@acmecorp.com
      🎯 Interest: Time savings
      
      Would you like to:
      
      1. 📅 Schedule a demo (15 min)
      2. 📄 Get a product overview PDF
      3. 💬 Ask questions now

User: Schedule a demo

Bot:  I can schedule you with our team!
      
      Available demo times:
      
      📅 Tomorrow (May 16)
         • 10:00 AM
         • 3:00 PM
      
      📅 Monday (May 19)
         • 11:00 AM
         • 2:00 PM
      
      Which works for you?

User: Tomorrow at 3pm

Bot:  ✅ Demo Scheduled!
      
      📅 Friday, May 16 at 3:00 PM
      👤 With: Alex from our Sales team
      📧 Calendar invite sent to maria@acmecorp.com
      
      Alex will show you how companies like Acme 
      save 10+ hours per week with our platform.
      
      See you tomorrow, Maria!

What It Can Do

• Qualify leads with questions
• Capture contact information
• Score leads automatically
• Schedule demo calls
• Send follow-up emails

IT Helpdesk

Best for: IT support tickets, troubleshooting, password resets

Sample Conversation

User: I can't access my email

Bot:  I'll help you troubleshoot your email access.
      
      What error are you seeing?
      
      1. 🔐 Password incorrect
      2. 📧 Can't connect to server
      3. 🔄 Email not syncing
      4. ❓ Something else

User: Password incorrect

Bot:  Let's fix your password issue.
      
      Have you tried resetting your password in the 
      last 24 hours?

User: No

Bot:  I can send a password reset link to your 
      backup email address.
      
      For security, please confirm your employee ID:

User: EMP-4521

Bot:  ✅ Verified! 
      
      I've sent a password reset link to your backup 
      email (j***@gmail.com).
      
      📧 Check your email and click the reset link
      ⏱️ Link expires in 15 minutes
      
      After resetting:
      1. Use the new password for email
      2. Update password on your phone too
      3. It may take 5 minutes to sync
      
      Still having issues after resetting?

User: It worked, thanks!

Bot:  Glad it's working! 🎉
      
      Quick security tips:
      • Use a strong, unique password
      • Enable two-factor authentication
      • Never share your password
      
      Anything else I can help with?

User: No that's all

Bot:  ✅ Ticket #IT-2025-0891 closed as resolved.
      
      Have a great day! Remember, I'm here 24/7 
      if you need IT help.

What It Can Do

• Create support tickets
• Reset passwords
• Troubleshoot common issues
• Check system status
• Escalate to human agents

Compliance & Privacy (LGPD/GDPR)

Best for: Handling data privacy requests

Sample Conversation

User: I want to see what data you have about me

Bot:  I can help you with a Data Access Request.
      
      Under privacy regulations (LGPD, GDPR, CCPA), 
      you have the right to receive a copy of your 
      personal data.
      
      To process your request, I need to verify your 
      identity. What's your email address?

User: john.doe@email.com

Bot:  I've sent a verification code to john.doe@email.com
      
      Please enter the 6-digit code:

User: 847291

Bot:  ✅ Identity verified!
      
      What would you like to do?
      
      1. 📥 Get a copy of my data
      2. ✏️ Correct my information
      3. 🗑️ Delete my data
      4. ❓ Ask about data usage

User: Get a copy of my data

Bot:  ✅ Data Access Request Submitted
      
      📋 Request #DSR-2025-0142
      📧 john.doe@email.com
      📅 Submitted: May 15, 2025
      ⏱️ Due: May 30, 2025 (15 days)
      
      We will compile all your personal data and 
      send it to your email in a secure format.
      
      You'll receive:
      • Profile information
      • Communication history
      • Preferences and settings
      • Activity logs
      
      Is there anything specific you're looking for?

User: No, that's all

Bot:  Your request is being processed.
      
      You'll receive an email within 15 days with 
      a secure link to download your data.
      
      Questions? Reply to the confirmation email 
      or come back here anytime.

Broadcast & Announcements

Best for: Sending company-wide messages, news updates

Sample Conversation (Admin)

Admin: Send an announcement

Bot:   I'll help you create an announcement.
       
       What's the title?

Admin: Office Closure Tomorrow

Bot:   Got it! Now the message content:

Admin: Due to the holiday, our office will be closed 
       tomorrow May 16. We'll reopen Monday at 9am.

Bot:   Who should receive this?
       
       1. 👥 All employees
       2. 🏢 Specific department
       3. 📍 Specific location
       4. 📋 Custom list

Admin: All employees

Bot:   How should I send it?
       
       ☑️ Email
       ☑️ Chat notification
       ☐ SMS
       
       (Select all that apply)

Admin: Email and chat

Bot:   📢 Announcement Preview:
       
       ━━━━━━━━━━━━━━━━━━━━━━━━━━━
       OFFICE CLOSURE TOMORROW
       ━━━━━━━━━━━━━━━━━━━━━━━━━━━
       
       Due to the holiday, our office will be 
       closed tomorrow May 16. We'll reopen 
       Monday at 9am.
       
       ━━━━━━━━━━━━━━━━━━━━━━━━━━━
       
       Recipients: 247 employees
       Channels: Email, Chat
       
       Send now or schedule?

Admin: Send now

Bot:   ✅ Announcement Sent!
       
       📧 247 emails delivered
       💬 247 chat notifications sent
       
       Delivery report saved. View in Analytics.

Talk to Data (Analytics)

Best for: Asking questions about your business data in plain English

Sample Conversation

User: How many sales did we make last month?

Bot:  📊 Sales Summary - April 2025
      
      Total Sales: 1,247
      Revenue: $156,340
      Average Order: $125.35
      
      Compared to March:
      • Sales: ▲ 12% (+134)
      • Revenue: ▲ 8% (+$11,520)

User: Which product sold the most?

Bot:  🏆 Top 5 Products - April 2025
      
      1. Widget Pro      - 342 units ($42,750)
      2. Basic Package   - 289 units ($28,900)
      3. Premium Bundle  - 201 units ($40,200)
      4. Starter Kit     - 187 units ($18,700)
      5. Add-on Pack     - 156 units ($15,600)
      
      Widget Pro has been #1 for 3 months in a row!

User: Show me sales by region

Bot:  🗺️ Sales by Region - April 2025
      
      North America    ████████████░░  $68,500 (44%)
      Europe           ███████░░░░░░░  $42,300 (27%)
      Asia Pacific     █████░░░░░░░░░  $31,200 (20%)
      Latin America    ██░░░░░░░░░░░░  $14,340 (9%)
      
      Fastest growing: Asia Pacific (▲ 23%)

User: Who are our top customers?

Bot:  👥 Top 5 Customers - April 2025
      
      1. Acme Corp         $12,450  (8 orders)
      2. TechStart Inc     $9,800   (12 orders)
      3. Global Services   $8,200   (5 orders)
      4. Smith & Co        $7,650   (6 orders)
      5. DataFlow Ltd      $6,900   (4 orders)
      
      Want me to show purchase history for any of these?

What It Can Do

• Answer business questions in plain English
• Show sales, revenue, customer data
• Compare time periods
• Create simple reports
• Export data to spreadsheets

Quick Template Selection Guide

Need Something Custom?

If these templates don’t fit your needs:

1. Start with the closest template - Modify it
2. Use the Default template - Build from scratch
3. Combine templates - Use features from multiple templates
4. Ask for help - Our community can guide you

See Also

• Templates Reference - Full template list
• How To: Create Your First Bot
• Sources App - Managing templates
• Write Your First Dialog

Business Intelligence Template (bi.gbai)

A General Bots template for automated business intelligence reporting and data visualization.

Overview

The BI template provides scheduled analytics reporting with automatic chart generation and delivery. It’s designed for organizations that need automated consumption reports, category analysis, and customer-specific insights.

Features

• Scheduled Reporting - Automated report generation on configurable schedules
• Time-Series Charts - Monthly consumption trends visualization
• Category Analysis - Product category breakdown with donut charts
• Per-Customer Reports - Individual customer consumption analysis
• Multi-Channel Delivery - Send reports via chat, email, or messaging platforms

Package Structure

bi.gbai/
├── bi.gbai/
│   ├── bi-admin.bas      # Administrative scheduled reports
│   └── bi-user.bas       # Per-customer report generation

Scripts

Configuration

Configure the template in your bot’s config.csv:

Usage

Administrative Reports

The bi-admin.bas script runs on a schedule and generates:

1. Monthly Consumption Chart - Time-series showing spending trends
2. Product Category Breakdown - Donut chart of spending by category

SET SCHEDULE "1 * * * * *"

billing = FIND "Orders"

' Monthly consumption
data = SELECT SUM(UnitPrice * Quantity) as Value, 
       MONTH(OrderDate)+'/'+YEAR(OrderDate) 
       FROM billing 
       GROUP BY MONTH(OrderDate), YEAR(OrderDate)

img = CHART "timeseries", data
SEND FILE img, "Monthly Consumption"

Per-Customer Reports

The bi-user.bas script iterates through customers to generate personalized reports:

customers = FIND "Customers"

FOR EACH c IN customers
    data = SELECT SUM(UnitPrice * Quantity) AS Value, 
           MONTH(OrderDate)+'/'+YEAR(OrderDate) 
           FROM billing
           JOIN Customers ON billing.CustomerID = Customers.CustomerID
           GROUP BY MONTH(OrderDate), YEAR(OrderDate)
           WHERE Customers.CustomerID = c.CustomerID

    img = CHART "timeseries", data
    SEND FILE img, "Monthly Consumption"
END FOR

Chart Types

The template supports various chart types:

Data Requirements

Orders Table Schema

The template expects a billing/orders data source with:

• OrderDate - Date of the transaction
• UnitPrice - Price per unit
• Quantity - Number of units
• ProductID - Foreign key to products
• CustomerID - Foreign key to customers

Products Table Schema

• ProductID - Primary key
• CategoryID - Foreign key to categories
• ProductName - Product name

Categories Table Schema

• CategoryID - Primary key
• CategoryName - Category display name

Example Output

Monthly Consumption Report

📊 Monthly Consumption Report
-----------------------------
Generated: 2024-01-15 08:00

[Time Series Chart Image]

Total Revenue: $125,430
Top Month: December ($18,500)
Growth Rate: +12% MoM

Category Breakdown

📊 Product Category Distribution
--------------------------------

[Donut Chart Image]

Electronics: 35%
Clothing: 28%
Home & Garden: 22%
Other: 15%

Customization

Adding New Reports

Create additional .bas files in the bi.gbai folder:

' sales-by-region.bas
SET SCHEDULE "0 9 * * 1"  ' Every Monday at 9 AM

data = SELECT Region, SUM(Amount) as Total 
       FROM Sales 
       GROUP BY Region

img = CHART "bar", data
SEND FILE img, "Weekly Regional Sales"

Customizing Delivery

Send reports to specific users or channels:

' Send to specific user
SEND FILE img TO "manager@company.com", "Weekly Report"

' Send to WhatsApp
SEND FILE img TO "+1234567890", "Your monthly report"

' Send to team channel
TALK TO "sales-team", img

Scheduling Options

Integration Examples

With CRM

' Combine with CRM data
opportunities = FIND "opportunities.csv"
revenue = SELECT stage, SUM(amount) FROM opportunities GROUP BY stage

img = CHART "funnel", revenue
SEND FILE img, "Sales Pipeline"

With ERP

' Inventory analysis
inventory = FIND "inventory.csv"
low_stock = SELECT product, quantity FROM inventory WHERE quantity < reorder_level

img = CHART "bar", low_stock
SEND FILE img, "Low Stock Alert"

Best Practices

1. Schedule appropriately - Don’t run heavy reports too frequently
2. Filter data - Use date ranges to limit data volume
3. Cache results - Store computed metrics for faster access
4. Log activities - Track report generation for auditing
5. Handle errors - Wrap queries in error handling

Troubleshooting

Related Templates

• Platform Analytics - Platform metrics and monitoring
• Talk to Data - Natural language data queries
• CRM - CRM with built-in reporting

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Web Crawler Template (crawler.gbai)

A General Bots template for automated web crawling and content extraction for knowledge base population.

Overview

The Crawler template enables your bot to automatically fetch, parse, and index web content. It’s designed for building knowledge bases from websites, monitoring web pages for changes, and extracting structured data from online sources.

Features

• Automated Web Scraping - Fetch and parse web pages automatically
• Document Mode - Answer questions based on crawled content
• Configurable Depth - Control how many pages to crawl
• Content Indexing - Automatically add content to knowledge base
• LLM Integration - Use AI to understand and summarize crawled content

Package Structure

crawler.gbai/
├── crawler.gbkb/          # Knowledge base for crawled content
│   └── docs/              # Indexed documents
└── crawler.gbot/
    └── config.csv         # Crawler configuration

Configuration

Configure the crawler in crawler.gbot/config.csv:

Example config.csv

name,value
Website,https://pragmatismo.com.br/
website Max Documents,2
Answer Mode,document
Theme Color,purple
LLM Provider,openai

How It Works

1. Initialization - Bot reads the target website from configuration
2. Crawling - Fetches pages starting from the root URL
3. Extraction - Parses HTML and extracts meaningful text content
4. Indexing - Stores content in the knowledge base for RAG
5. Q&A - Users can ask questions about the crawled content

Usage

Basic Setup

1. Copy the template to your bot’s packages directory:

cp -r templates/crawler.gbai /path/to/your/bot/packages/

2. Edit crawler.gbot/config.csv with your target website:

name,value
Website,https://your-website.com/
website Max Documents,10
Answer Mode,document

3. Deploy and the bot will automatically crawl the configured site.

Querying Crawled Content

Once crawled, users can ask questions naturally:

• “What services does the company offer?”
• “Tell me about the pricing”
• “Summarize the about page”
• “What are the main features?”

Answer Modes

Sample Conversation

User: What does this company do?

Bot:  Based on the website content:
      
      Pragmatismo provides enterprise AI solutions 
      including:
      
      • General Bots platform
      • Custom AI development
      • Conversational AI consulting
      • Integration services
      
      📄 Source: pragmatismo.com.br/about

User: Do they have any case studies?

Bot:  Yes! According to the website, they have worked 
      with several enterprise clients:
      
      • Banking sector automation
      • Healthcare chatbots
      • E-commerce customer service
      
      📄 Source: pragmatismo.com.br/cases

User: How can I contact them?

Bot:  Contact information from the website:
      
      📧 Email: contact@pragmatismo.com.br
      📍 Location: São Paulo, Brazil
      🌐 Website: pragmatismo.com.br
      
      📄 Source: pragmatismo.com.br/contact

Advanced Configuration

Limiting Crawl Scope

Control which pages are crawled:

name,value
Website,https://example.com/docs/
website Max Documents,50
Website Include Pattern,/docs/*
Website Exclude Pattern,/docs/archive/*

Scheduling Recrawls

Set up periodic recrawling to keep content fresh:

name,value
Website Refresh Schedule,0 0 * * 0

This example recrawls every Sunday at midnight.

Authentication

For sites requiring authentication:

name,value
Website Auth Type,basic
Website Username,user
Website Password,secret

Customization

Creating Custom Crawl Logic

Create a BASIC dialog for custom crawling:

' custom-crawl.bas
urls = ["https://site1.com", "https://site2.com", "https://site3.com"]

FOR EACH url IN urls
    content = GET url
    
    IF content THEN
        SAVE "crawled_pages.csv", url, content, NOW()
        SET CONTEXT content
    END IF
NEXT

TALK "Crawled " + UBOUND(urls) + " pages successfully."

Processing Crawled Content

Use LLM to process and structure crawled data:

' process-crawled.bas
pages = FIND "crawled_pages.csv"

FOR EACH page IN pages
    summary = LLM "Summarize this content in 3 bullet points: " + page.content
    
    WITH processed
        url = page.url
        summary = summary
        processed_at = NOW()
    END WITH
    
    SAVE "processed_content.csv", processed
NEXT

Extracting Structured Data

Extract specific information from pages:

' extract-products.bas
SET CONTEXT "You are a data extraction assistant. Extract product information as JSON."

page_content = GET "https://store.example.com/products"

products = LLM "Extract all products with name, price, and description as JSON array: " + page_content

SAVE "products.json", products

Integration Examples

With Knowledge Base

' Add crawled content to KB
content = GET "https://docs.example.com/api"

IF content THEN
    USE KB "api-docs.gbkb"
    ADD TO KB content, "API Documentation"
END IF

With Notifications

' Monitor for changes
previous = GET BOT MEMORY "last_content"
current = GET "https://news.example.com"

IF current <> previous THEN
    SEND MAIL "admin@company.com", "Website Changed", "The monitored page has been updated.", []
    SET BOT MEMORY "last_content", current
END IF

Best Practices

1. Respect robots.txt - Only crawl pages allowed by the site’s robots.txt
2. Rate limiting - Don’t overwhelm target servers with requests
3. Set reasonable limits - Start with low Max Documents values
4. Monitor content quality - Review crawled content for accuracy
5. Keep content fresh - Schedule periodic recrawls for dynamic sites
6. Handle errors gracefully - Implement retry logic for failed requests

Troubleshooting

Limitations

• JavaScript-rendered content may not be fully captured
• Some sites block automated crawlers
• Large sites may take significant time to fully crawl
• Dynamic content may require special handling

Use Cases

• Documentation Bots - Index product docs for support
• Competitive Intelligence - Monitor competitor websites
• News Aggregation - Collect news from multiple sources
• Research Assistants - Build knowledge bases from academic sources
• FAQ Generators - Extract FAQs from help sites

Related Templates

• AI Search - AI-powered document search
• Talk to Data - Natural language data queries
• Law - Legal document processing with similar RAG approach

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbkb Reference - Knowledge base guide

Legal Document Processing Template (law.gbai)

A General Bots template for legal case management, document analysis, and AI-powered legal Q&A.

Overview

The Law template enables legal professionals to load case documents, query case information using natural language, and get AI-assisted analysis of legal materials. It’s designed for law firms, legal departments, and compliance teams who need efficient document-based legal research.

Features

• Case Document Loading - Load and index PDF case files by case number
• Document Q&A - Ask questions about loaded legal documents
• Context-Aware Responses - AI responses grounded in actual case content
• Case Summarization - Generate summaries of case documents
• Multi-Document Support - Work with multiple cases simultaneously
• Audit Trail - Track all document access and queries

Package Structure

law.gbai/
├── law.gbdialog/
│   └── case.bas           # Case loading and query handler
├── law.gbdrive/           # Case document storage
│   └── (case-*.pdf)       # Case PDF files
├── law.gbkb/              # Knowledge base for legal reference
└── law.gbot/
    └── config.csv         # Bot configuration

Scripts

How It Works

Case Loading Flow

1. User provides a case number (e.g., “12345”)
2. Bot searches for case-12345.pdf in the drive
3. Document content is extracted and set as context
4. Answer mode switches to “document” for grounded responses
5. User can ask questions about the loaded case

Code Example

PARAM cod AS STRING LIKE "12345" DESCRIPTION "Case number to load and query"

DESCRIPTION "Load a legal case document by case number for Q&A and analysis"

text = GET "case-" + cod + ".pdf"

IF text THEN
    SET CONTEXT "Based on this document, answer the person's questions:\n\n" + text
    SET ANSWER MODE "document"
    TALK "Case ${cod} loaded. Ask me anything about the case or request a summary."
ELSE
    TALK "Case not found. Please check the case number."
END IF

Configuration

Configure in law.gbot/config.csv:

Sample Conversation

User: Load case 12345

Bot:  Case 12345 loaded. Ask me anything about the case 
      or request a summary.

User: What are the main claims in this case?

Bot:  Based on the document, the main claims are:
      
      1. Breach of contract regarding the delivery terms 
         in Section 3.2
      2. Failure to meet quality standards as specified 
         in Exhibit A
      3. Request for damages in the amount of $250,000
      
      📄 Source: Case 12345, Pages 3-5

User: Summarize the defendant's response

Bot:  The defendant argues that:
      
      • Delivery delays were caused by force majeure events 
        (documented in Exhibit C)
      • Quality standards were met according to third-party 
        inspection report
      • Damages claimed are excessive and not substantiated 
        by evidence
      
      📄 Source: Case 12345, Pages 12-18

User: What are the key dates mentioned?

Bot:  Key dates from the case file:
      
      📅 Contract signed: January 15, 2024
      📅 Delivery due date: March 30, 2024
      📅 Actual delivery: April 22, 2024
      📅 Complaint filed: May 10, 2024
      📅 Response deadline: June 15, 2024
      
      📄 Source: Case 12345, Pages 1-2

Document Naming Convention

Case documents should follow this naming pattern:

case-{case_number}.pdf

Examples:

• case-12345.pdf
• case-2024-CV-0001.pdf
• case-APPEAL-789.pdf

Customization

Adding Case Search

' search-cases.bas
PARAM query AS STRING DESCRIPTION "Search term for finding cases"

DESCRIPTION "Search for cases by party name, date, or keywords"

cases = FIND "case_index.csv", "content LIKE '%" + query + "%'"

IF UBOUND(cases) > 0 THEN
    TALK "Found " + UBOUND(cases) + " matching cases:"
    
    FOR EACH c IN cases
        TALK "- Case " + c.case_number + ": " + c.title
    NEXT
ELSE
    TALK "No cases found matching: " + query
END IF

Case Summarization

' summarize-case.bas
PARAM cod AS STRING DESCRIPTION "Case number to summarize"

DESCRIPTION "Generate an executive summary of a legal case"

text = GET "case-" + cod + ".pdf"

IF text THEN
    summary = LLM "As a legal professional, provide an executive summary of this case including: 
                   1. Parties involved
                   2. Key facts
                   3. Legal issues
                   4. Current status
                   5. Next steps
                   
                   Document: " + text
    
    TALK "## Case " + cod + " Summary\n\n" + summary
    
    ' Save summary for future reference
    SAVE "case_summaries.csv", cod, summary, NOW()
ELSE
    TALK "Case not found."
END IF

Supporting Multiple Document Types

' load-document.bas
PARAM doc_type AS STRING LIKE "contract" DESCRIPTION "Type: case, contract, brief, motion"
PARAM doc_id AS STRING DESCRIPTION "Document identifier"

DESCRIPTION "Load various legal document types"

filename = doc_type + "-" + doc_id + ".pdf"
text = GET filename

IF text THEN
    SET CONTEXT "This is a legal " + doc_type + ". Answer questions based on its content:\n\n" + text
    SET ANSWER MODE "document"
    TALK "Loaded " + doc_type + " " + doc_id + ". Ready for questions."
ELSE
    TALK "Document not found: " + filename
END IF

Compliance Logging

' Add audit logging to case.bas
IF text THEN
    ' Log access for compliance
    WITH audit_entry
        timestamp = NOW()
        user = GET SESSION "user_email"
        case_number = cod
        action = "document_access"
        ip_address = GET SESSION "client_ip"
    END WITH
    
    SAVE "legal_audit_log.csv", audit_entry
    
    SET CONTEXT "Based on this document..." + text
END IF

Integration Examples

With Calendar

' Schedule case deadlines
deadline = LLM "Extract the next deadline date from this case: " + text

IF deadline THEN
    CREATE CALENDAR EVENT "Case " + cod + " Deadline", deadline
    TALK "Deadline added to calendar: " + deadline
END IF

With Email

' Email case summary to team
summary = LLM "Summarize the key points of this case in 3 paragraphs: " + text

SEND MAIL "legal-team@firm.com", "Case " + cod + " Summary", summary, []
TALK "Summary sent to legal team."

With Document Generation

' Generate response document
response = LLM "Draft a formal response letter addressing the claims in this case: " + text

CREATE DRAFT response, "Response to Case " + cod
TALK "Draft response created. Review in your documents."

Security Considerations

1. Access Control - Implement role-based access for sensitive cases
2. Audit Logging - Log all document access for compliance
3. Data Encryption - Enable encryption for stored documents
4. Session Timeout - Configure appropriate session timeouts
5. Authentication - Require strong authentication for legal systems
6. Data Retention - Follow legal data retention requirements

Best Practices

1. Organize documents - Use consistent naming conventions
2. Index cases - Maintain a searchable case index
3. Regular backups - Back up case documents frequently
4. Version control - Track document versions
5. Clear context - Clear previous case context before loading new cases
6. Verify AI responses - Always verify AI-generated legal content

Troubleshooting

Limitations

• PDF documents must be text-based (not scanned images)
• Very large documents may require chunking
• Complex legal analysis should be verified by professionals
• AI responses are assistive, not legal advice

Use Cases

• Case Research - Quickly find relevant information in case files
• Document Review - AI-assisted document analysis
• Client Communication - Generate case status summaries
• Deadline Tracking - Extract and track important dates
• Knowledge Management - Build searchable legal knowledge bases

Disclaimer

This template provides AI-assisted document analysis tools. It does not constitute legal advice. All AI-generated content should be reviewed by qualified legal professionals. Users are responsible for ensuring compliance with applicable legal and ethical standards.

Related Templates

• HIPAA Medical - Healthcare compliance
• Talk to Data - Natural language document queries
• AI Search - AI-powered document search

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbkb Reference - Knowledge base guide

LLM Server Template (llm-server.gbai)

A General Bots template for deploying LLM-powered web services that process orders and requests via API endpoints.

Overview

The LLM Server template transforms General Bots into a headless API service that processes structured requests using LLM intelligence. It’s designed for integrating AI-powered order processing, chatbot backends, and automated response systems into existing applications.

Features

• REST API Endpoints - HTTP endpoints for bot interaction
• Order Processing - Structured JSON responses for orders
• Product Catalog Integration - Dynamic product menu from CSV
• System Prompt Configuration - Customizable AI behavior
• Session Management - Track conversations across requests
• Operator Support - Multi-operator/tenant architecture

Package Structure

llm-server.gbai/
├── llm-server.gbdata/      # Data files
│   └── products.csv        # Product catalog
├── llm-server.gbdialog/
│   └── start.bas           # Main dialog with system prompt
├── llm-server.gbkb/        # Knowledge base
└── llm-server.gbot/
    └── config.csv          # Bot configuration

API Endpoints

Start a Session

POST https://{host}/{botId}/dialogs/start
Content-Type: application/x-www-form-urlencoded

operator=123
userSystemId=999

Response:

{
  "pid": "1237189231897",
  "conversationId": "abc123",
  "status": "started"
}

Send a Message

POST https://{host}/api/dk/messageBot
Content-Type: application/x-www-form-urlencoded

pid=1237189231897
text=I want a banana

Response:

{
  "orderedItems": [
    {
      "item": {
        "id": 102,
        "price": 0.30,
        "name": "Banana",
        "quantity": 1,
        "notes": ""
      }
    }
  ],
  "userId": "123",
  "accountIdentifier": "TableA",
  "deliveryTypeId": 2
}

Configuration

System Prompt

The start.bas defines the AI behavior:

PARAM operator AS number LIKE 12312312 DESCRIPTION "Operator code."
DESCRIPTION It is a WebService of GB.

products = FIND "products.csv"

BEGIN SYSTEM PROMPT

You are a chatbot assisting a store attendant in processing orders. Follow these rules:

1. **Order Format**: Each order must include the product name, the table number, and the customer's name.

2. **Product Details**: The available products are:
   
   ${TOYAML(products)}

3. **JSON Response**: For each order, return a valid RFC 8259 JSON object containing:
   - product name
   - table number

4. **Guidelines**:
   - Do **not** engage in conversation.
   - Return the response in plain text JSON format only.

END SYSTEM PROMPT

Product Catalog

Create products.csv in the llm-server.gbdata folder:

id,name,price,category,description
101,Apple,0.50,Fruit,Fresh red apple
102,Banana,0.30,Fruit,Ripe yellow banana
103,Orange,0.40,Fruit,Juicy orange
201,Milk,1.20,Dairy,1 liter whole milk
202,Cheese,2.50,Dairy,200g cheddar

Bot Configuration

Configure in llm-server.gbot/config.csv:

Usage Examples

cURL Examples

Start Session:

curl -X POST https://api.example.com/llmservergbot/dialogs/start \
  -d "operator=123" \
  -d "userSystemId=999"

Send Order:

curl -X POST https://api.example.com/api/dk/messageBot \
  -d "pid=1237189231897" \
  -d "text=I need 2 apples and 1 milk"

JavaScript Integration

async function startBotSession(operator, userId) {
  const response = await fetch('https://api.example.com/llmservergbot/dialogs/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ operator, userSystemId: userId })
  });
  return response.json();
}

async function sendMessage(pid, text) {
  const response = await fetch('https://api.example.com/api/dk/messageBot', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ pid, text })
  });
  return response.json();
}

// Usage
const session = await startBotSession('123', '999');
const order = await sendMessage(session.pid, 'I want a banana');
console.log(order.orderedItems);

Python Integration

import requests

class LLMServerClient:
    def __init__(self, base_url, operator):
        self.base_url = base_url
        self.operator = operator
        self.pid = None
    
    def start_session(self, user_id):
        response = requests.post(
            f"{self.base_url}/llmservergbot/dialogs/start",
            data={"operator": self.operator, "userSystemId": user_id}
        )
        self.pid = response.json()["pid"]
        return self.pid
    
    def send_message(self, text):
        response = requests.post(
            f"{self.base_url}/api/dk/messageBot",
            data={"pid": self.pid, "text": text}
        )
        return response.json()

# Usage
client = LLMServerClient("https://api.example.com", "123")
client.start_session("999")
order = client.send_message("I need 2 bananas")
print(order)

Response Format

Order Response Structure

{
  "orderedItems": [
    {
      "item": {
        "id": 102,
        "price": 0.30,
        "name": "Banana",
        "sideItems": [],
        "quantity": 2,
        "notes": "ripe ones please"
      }
    }
  ],
  "userId": "123",
  "accountIdentifier": "Table5",
  "deliveryTypeId": 2
}

Field Descriptions

Customization

Custom Response Format

Modify the system prompt for different output structures:

BEGIN SYSTEM PROMPT
Return responses as JSON with this structure:
{
  "intent": "order|question|complaint",
  "entities": [...extracted entities...],
  "response": "...",
  "confidence": 0.0-1.0
}
END SYSTEM PROMPT

Adding Validation

' Validate order before returning
order = LLM_RESPONSE

IF NOT order.orderedItems THEN
    RETURN {"error": "No items in order", "suggestion": "Please specify products"}
END IF

FOR EACH item IN order.orderedItems
    product = FIND "products.csv", "id = " + item.item.id
    IF NOT product THEN
        RETURN {"error": "Invalid product ID: " + item.item.id}
    END IF
NEXT

RETURN order

Multi-Language Support

PARAM language AS STRING LIKE "en" DESCRIPTION "Response language"

BEGIN SYSTEM PROMPT
Respond in ${language} language.
Available products: ${TOYAML(products)}
Return JSON format only.
END SYSTEM PROMPT

Error Handling

Common Error Responses

{
  "error": "session_expired",
  "message": "Please start a new session",
  "code": 401
}

{
  "error": "invalid_request",
  "message": "Missing required parameter: text",
  "code": 400
}

{
  "error": "product_not_found",
  "message": "Product 'pizza' is not in our catalog",
  "code": 404
}

Best Practices

1. Keep prompts focused - Single-purpose system prompts work better
2. Validate responses - Always validate LLM output before returning
3. Handle edge cases - Plan for invalid products, empty orders
4. Monitor usage - Track API calls and response times
5. Rate limiting - Implement rate limits for production
6. Secure endpoints - Use authentication for production APIs
7. Log requests - Maintain audit logs for debugging

Deployment

Environment Variables

LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-5
API_RATE_LIMIT=100
SESSION_TIMEOUT=3600

Docker Deployment

FROM generalbots/server:latest
COPY llm-server.gbai /app/packages/
ENV API_MODE=true
EXPOSE 4242
CMD ["npm", "start"]

Troubleshooting

Use Cases

• Restaurant Ordering - Process food orders via API
• Retail POS Integration - AI-powered point of sale
• Chatbot Backend - Headless chatbot for web/mobile apps
• Voice Assistant Backend - Process voice-to-text commands
• Order Automation - Automate order entry from various sources

Related Templates

• LLM Tools - LLM with tool/function calling
• Store - Full e-commerce with order processing
• API Client - API integration examples

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

LLM Tools Template (llm-tools.gbai)

A General Bots template demonstrating how to create and register custom tools (functions) that LLMs can call during conversations.

Overview

The LLM Tools template shows how to extend your bot’s capabilities by creating tools that the AI can invoke automatically. Tools enable the LLM to perform actions like database lookups, API calls, calculations, and more—all triggered naturally through conversation.

Features

• Custom Tool Registration - Define tools the LLM can call
• Parameter Validation - Type-safe tool parameters with descriptions
• Knowledge Base Integration - Combine tools with RAG
• Natural Interaction - Users don’t need to know tool names
• Extensible Architecture - Easy to add new tools

Package Structure

llm-tools.gbai/
├── llm-tools.gbdata/       # Data files for tools
│   └── products.csv        # Product catalog
├── llm-tools.gbdialog/
│   ├── start.bas           # Main dialog with tool registration
│   └── get-price.bas       # Example tool implementation
├── llm-tools.gbkb/         # Knowledge base
│   └── products.gbkb/      # Product documentation
└── llm-tools.gbot/
    └── config.csv          # Bot configuration

Scripts

How Tools Work

1. Tool Registration

In start.bas, tools are registered with ADD TOOL:

ADD TOOL "get-price"

USE KB "products.gbkb"

CLEAR SUGGESTIONS

ADD SUGGESTION "price" AS "Check product price"
ADD SUGGESTION "products" AS "View products"
ADD SUGGESTION "help" AS "How to use"

BEGIN TALK
**Product Assistant**

I can help you check product prices and information.

Just ask me about any product and I'll look it up for you.
END TALK

BEGIN SYSTEM PROMPT
You are a product assistant with access to internal tools.

When get-price returns -1, the product does not exist.
When asked about a price, use the get-price tool and return the result.

Do not expose tool names to users - just act on their requests naturally.
END SYSTEM PROMPT

2. Tool Implementation

Each tool is a separate .bas file with PARAM and DESCRIPTION:

PARAM product AS STRING LIKE "fax" DESCRIPTION "Name of the product to get price for"

DESCRIPTION "Get the price of a product by name from the product catalog"

productRecord = FIND "products.csv", "name = ${product}"

IF productRecord THEN
    RETURN productRecord.price
ELSE
    RETURN -1
END IF

3. LLM Invocation

When a user asks “How much is the fax machine?”, the LLM:

1. Recognizes this requires price information
2. Calls get-price with product="fax"
3. Receives the price (or -1 if not found)
4. Formulates a natural response

Sample Conversation

User: How much does the wireless mouse cost?

Bot:  [Calls get-price with product="wireless mouse"]
      The wireless mouse is $29.99.

User: What about the keyboard?

Bot:  [Calls get-price with product="keyboard"]
      The standard keyboard is $49.99. We also have a 
      mechanical keyboard for $89.99.

User: Is the laptop in stock and what's the price?

Bot:  [Calls get-price with product="laptop"]
      [Calls check-inventory with sku="LAPTOP-001"]
      The laptop is $999. Good news - we have 12 units 
      available in our main warehouse!

User: I want 3 monitors with my 20% employee discount

Bot:  [Calls get-price with product="monitor"]
      [Calls calculate-discount with price=299, percent=20]
      Each monitor is $299, but with your 20% employee 
      discount, you'll pay $239.20 each. 
      For 3 monitors: $717.60 (saving $179.40)!

Creating Custom Tools

Tool Anatomy

Every tool needs:

• PARAM declarations - Input parameters with types and examples
• DESCRIPTION - What the tool does (for LLM understanding)
• Implementation - The actual logic
• RETURN - The output value

Parameter Types

Example Tools

Database Lookup Tool

' lookup-customer.bas
PARAM customer_id AS STRING LIKE "CUST-001" DESCRIPTION "Customer ID to look up"

DESCRIPTION "Retrieve customer information by ID"

customer = FIND "customers.csv", "id = ${customer_id}"

IF customer THEN
    WITH result
        name = customer.name
        email = customer.email
        status = customer.status
        since = customer.created_at
    END WITH
    RETURN result
ELSE
    RETURN NULL
END IF

Calculation Tool

' calculate-discount.bas
PARAM original_price AS NUMBER LIKE 100 DESCRIPTION "Original product price"
PARAM discount_percent AS NUMBER LIKE 15 DESCRIPTION "Discount percentage"

DESCRIPTION "Calculate the final price after applying a discount"

discount_amount = original_price * (discount_percent / 100)
final_price = original_price - discount_amount

WITH result
    original = original_price
    discount = discount_amount
    final = final_price
    savings = discount_percent + "% off"
END WITH

RETURN result

API Integration Tool

' check-inventory.bas
PARAM sku AS STRING LIKE "SKU-12345" DESCRIPTION "Product SKU to check"
PARAM warehouse AS STRING LIKE "main" DESCRIPTION "Warehouse location" OPTIONAL

DESCRIPTION "Check real-time inventory levels for a product"

IF NOT warehouse THEN
    warehouse = "main"
END IF

SET HEADER "Authorization" AS "Bearer " + GET ENV "INVENTORY_API_KEY"
response = GET "https://api.inventory.com/stock/" + sku + "?warehouse=" + warehouse

IF response.error THEN
    RETURN {"available": false, "error": response.error}
END IF

WITH result
    sku = sku
    available = response.quantity > 0
    quantity = response.quantity
    warehouse = warehouse
    last_updated = response.timestamp
END WITH

RETURN result

Email Sending Tool

' send-notification.bas
PARAM recipient AS EMAIL LIKE "user@example.com" DESCRIPTION "Email recipient"
PARAM subject AS STRING LIKE "Order Confirmation" DESCRIPTION "Email subject"
PARAM message AS STRING DESCRIPTION "Email body content"

DESCRIPTION "Send an email notification to a customer"

SEND MAIL recipient, subject, message, []

WITH result
    sent = true
    recipient = recipient
    timestamp = NOW()
END WITH

RETURN result

Tool Registration Patterns

Single Tool

ADD TOOL "get-price"

Multiple Tools

ADD TOOL "get-price"
ADD TOOL "check-inventory"
ADD TOOL "lookup-customer"
ADD TOOL "calculate-discount"
ADD TOOL "send-notification"

Conditional Tools

user_role = GET SESSION "user_role"

ADD TOOL "get-price"
ADD TOOL "check-inventory"

IF user_role = "admin" THEN
    ADD TOOL "update-price"
    ADD TOOL "delete-product"
END IF

System Prompt Best Practices

Guide the LLM on when and how to use tools:

BEGIN SYSTEM PROMPT
You are a helpful product assistant with access to the following capabilities:

**Available Tools:**
- get-price: Look up product prices by name
- check-inventory: Check stock availability
- calculate-discount: Calculate prices with discounts

**Guidelines:**
1. When users ask about prices, use the get-price tool
2. When asked about availability, use check-inventory
3. If a tool returns an error, explain politely that the item wasn't found
4. Never mention tool names to users - just provide the information naturally
5. Combine multiple tool results when needed to answer complex questions

**Error Handling:**
- If get-price returns -1, the product doesn't exist
- If check-inventory shows quantity 0, inform the user it's out of stock
END SYSTEM PROMPT

Configuration

Configure in llm-tools.gbot/config.csv:

Error Handling

In Tool Implementation

' get-price.bas with error handling
PARAM product AS STRING LIKE "laptop" DESCRIPTION "Product name"

DESCRIPTION "Get product price with error handling"

ON ERROR GOTO HandleError

productRecord = FIND "products.csv", "name LIKE '%" + product + "%'"

IF productRecord THEN
    RETURN productRecord.price
ELSE
    RETURN {"error": "not_found", "message": "Product not in catalog"}
END IF

HandleError:
    RETURN {"error": "system_error", "message": "Unable to look up price"}

In System Prompt

BEGIN SYSTEM PROMPT
When tools return errors:
- "not_found": Apologize and suggest similar products
- "out_of_stock": Offer to notify when back in stock
- "system_error": Ask user to try again later
END SYSTEM PROMPT

Testing Tools

Manual Testing

' test-tools.bas
result = CALL "get-price", {"product": "laptop"}
TALK "Price result: " + JSON(result)

result = CALL "check-inventory", {"sku": "LAPTOP-001"}
TALK "Inventory result: " + JSON(result)

Conversation Testing

Test various phrasings to ensure tool invocation:

• “What’s the price of X?”
• “How much does X cost?”
• “Price for X please”
• “X price?”
• “Can you tell me what X costs?”

Best Practices

1. Clear descriptions - Help the LLM understand when to use each tool
2. Good examples - LIKE clauses guide parameter format
3. Handle errors - Always return meaningful error responses
4. Validate input - Check parameters before processing
5. Log tool calls - Track usage for debugging
6. Keep tools focused - One tool, one purpose
7. Test thoroughly - Various phrasings should trigger correct tools

Troubleshooting

Use Cases

• Product Lookup - Price, availability, specifications
• Customer Service - Order status, account info
• Calculations - Quotes, discounts, shipping
• Integrations - CRM, ERP, external APIs
• Data Access - Database queries, report generation

Related Templates

• LLM Server - Headless API with LLM processing
• CRM - CRM with many tool examples
• Store - E-commerce with product tools
• Talk to Data - Data query tools

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

API Client Template (api-client.gbai)

A General Bots template demonstrating REST API integration patterns for connecting to external services and data sources.

Overview

The API Client template provides examples and patterns for integrating General Bots with external REST APIs. It includes examples for weather services, Microsoft Partner Center integration, and general HTTP request patterns that can be adapted for any API.

Features

• REST API Integration - GET, POST, PUT, DELETE request patterns
• Authentication - OAuth, Bearer tokens, API keys
• Header Management - Custom headers for API requirements
• Pagination Support - Handle paginated API responses
• Data Synchronization - Sync external data to local tables
• Scheduled Jobs - Automated API polling and sync

Package Structure

api-client.gbai/
├── api-client.gbdialog/
│   ├── climate.bas              # Weather API example
│   └── msft-partner-center.bas  # Microsoft Partner Center integration
└── api-client.gbot/
    └── config.csv               # Bot configuration

Scripts

Basic API Patterns

Simple GET Request

' Get data from an API
response = GET "https://api.example.com/data"

IF response THEN
    TALK "Data received: " + response.value
ELSE
    TALK "Failed to fetch data"
END IF

POST Request with Body

' Send data to an API
SET HEADER "Content-Type" AS "application/json"

payload = {"name": "John", "email": "john@example.com"}
response = POST "https://api.example.com/users", payload

IF response.id THEN
    TALK "User created with ID: " + response.id
END IF

PUT Request for Updates

' Update existing resource
SET HEADER "Content-Type" AS "application/json"

updates = {"status": "active", "role": "admin"}
response = PUT "https://api.example.com/users/123", updates

TALK "User updated: " + response.status

DELETE Request

' Delete a resource
response = DELETE "https://api.example.com/users/123"

IF response.deleted THEN
    TALK "User deleted successfully"
END IF

Authentication Patterns

API Key Authentication

SET HEADER "X-API-Key" AS "your-api-key-here"

response = GET "https://api.example.com/protected-resource"

Bearer Token Authentication

SET HEADER "Authorization" AS "Bearer " + access_token

response = GET "https://api.example.com/user/profile"

OAuth 2.0 Token Exchange

' Get OAuth token
SET HEADER "Content-Type" AS "application/x-www-form-urlencoded"

tokenResponse = POST "https://auth.example.com/oauth/token", 
    "grant_type=client_credentials&client_id=" + clientId + 
    "&client_secret=" + clientSecret

access_token = tokenResponse.access_token

' Use token for API calls
SET HEADER "Authorization" AS "Bearer " + access_token
data = GET "https://api.example.com/resources"

Basic Authentication

credentials = BASE64(username + ":" + password)
SET HEADER "Authorization" AS "Basic " + credentials

response = GET "https://api.example.com/secure-endpoint"

Weather API Example

The climate.bas tool demonstrates a simple API integration:

PARAM location AS "The city and state, e.g. San Francisco, CA"
PARAM unit AS "celsius", "fahrenheit"

DESCRIPTION "Get the current weather in a given location"

' Implementation would call weather API
' response = GET "https://api.weather.com/current?location=" + location

RETURN weather_info

Sample Conversation

User: What's the weather in New York?

Bot:  [Calls climate tool with location="New York"]
      It's currently 72°F and sunny in New York, NY.
      
      Today's forecast:
      🌡️ High: 78°F / Low: 65°F
      💧 Humidity: 45%
      💨 Wind: 8 mph NW

User: What about São Paulo in celsius?

Bot:  [Calls climate tool with location="São Paulo", unit="celsius"]
      It's currently 24°C and partly cloudy in São Paulo, Brazil.
      
      Today's forecast:
      🌡️ High: 28°C / Low: 19°C
      💧 Humidity: 62%
      💨 Wind: 12 km/h SE

Microsoft Partner Center Integration

The msft-partner-center.bas demonstrates a complex enterprise API integration:

Features

• OAuth token authentication with Azure AD
• Multi-resource synchronization (Customers, Subscriptions, Billing)
• Scheduled execution
• Pagination handling
• Database table management

Configuration

' Required parameters
tenantId = GET ENV "AZURE_TENANT_ID"
clientId = GET ENV "AZURE_CLIENT_ID"
clientSecret = GET ENV "AZURE_CLIENT_SECRET"
host = "https://api.partnercenter.microsoft.com"

Scheduled Sync

SET SCHEDULE "1 * * * * *"  ' Run periodically

' Set required headers
SET HEADER "MS-Contract-Version" AS "v1"
SET HEADER "MS-CorrelationId" AS UUID()
SET HEADER "MS-RequestId" AS UUID()
SET HEADER "MS-PartnerCenter-Application" AS "General Bots"
SET HEADER "X-Locale" AS "en-US"

Sync Customers and Subscriptions

SET PAGE MODE "none"
customers = GET host + "/v1/customers?size=20000"

MERGE "Customers" WITH customers.items BY "Id"

FOR EACH customer IN customers
    subs = GET host + "/v1/customers/" + customer.id + "/subscriptions"
    MERGE "Subscriptions" WITH subs.items BY "Id"
END FOR

Billing Data Sync

SET PAGE MODE "auto"
billingItems = GET host + "/v1/invoices/unbilled/lineitems" + 
    "?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=USD"

FOR EACH item IN billingItems
    SAVE "Billing", item.alternateId, item.customerId, item.productName,
         item.quantity, item.unitPrice, item.subtotal, item.chargeStartDate
END FOR

Table Definitions

TABLE Billing
    CustomerId Customers
    ResourceGroup string(200)
    CustomerName string(400)
    ProductName string(400)
    Quantity double
    UnitPrice double
    Subtotal double
    ChargeStartDate date
    ChargeEndDate date
END TABLE

TABLE Customers
    TenantId guid
    CompanyName string(100)
    Id guid
END TABLE

TABLE Subscriptions
    CustomerId Customers
    Id guid
    OfferName string(50)
END TABLE

Custom API Integration

Creating Your Own API Client

' my-api-client.bas
PARAM resource AS STRING LIKE "users" DESCRIPTION "API resource to fetch"
PARAM filters AS STRING LIKE "status=active" DESCRIPTION "Query filters" OPTIONAL

DESCRIPTION "Fetch data from custom API"

' Configuration
api_base = GET ENV "MY_API_BASE_URL"
api_key = GET ENV "MY_API_KEY"

' Set authentication
SET HEADER "Authorization" AS "Bearer " + api_key
SET HEADER "Content-Type" AS "application/json"

' Build URL
url = api_base + "/" + resource
IF filters THEN
    url = url + "?" + filters
END IF

' Make request
response = GET url

IF response.error THEN
    RETURN {"success": false, "error": response.error}
END IF

RETURN {"success": true, "data": response.data, "count": UBOUND(response.data)}

Handling Pagination

' paginated-fetch.bas
PARAM endpoint AS STRING DESCRIPTION "API endpoint"

DESCRIPTION "Fetch all pages from a paginated API"

all_results = []
page = 1
has_more = true

DO WHILE has_more
    response = GET endpoint + "?page=" + page + "&per_page=100"
    
    IF response.data THEN
        all_results = MERGE all_results, response.data
        
        IF UBOUND(response.data) < 100 THEN
            has_more = false
        ELSE
            page = page + 1
        END IF
    ELSE
        has_more = false
    END IF
LOOP

RETURN all_results

Error Handling with Retry

' api-with-retry.bas
PARAM url AS STRING DESCRIPTION "API URL to call"
PARAM max_retries AS INTEGER LIKE 3 DESCRIPTION "Maximum retry attempts"

DESCRIPTION "API call with automatic retry on failure"

retries = 0
success = false

DO WHILE retries < max_retries AND NOT success
    response = GET url
    
    IF response.error THEN
        retries = retries + 1
        WAIT retries * 2  ' Exponential backoff
    ELSE
        success = true
    END IF
LOOP

IF success THEN
    RETURN response
ELSE
    RETURN {"error": "Max retries exceeded", "last_error": response.error}
END IF

Configuration

Configure in api-client.gbot/config.csv:

Environment Variables

Store sensitive values as environment variables:

MY_API_KEY=your-api-key
MY_API_SECRET=your-secret
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Access in BASIC:

api_key = GET ENV "MY_API_KEY"

Common HTTP Headers

Best Practices

1. Secure credentials - Never hardcode API keys; use environment variables
2. Handle errors - Always check for error responses
3. Rate limiting - Respect API rate limits with delays
4. Pagination - Handle paginated responses properly
5. Logging - Log API calls for debugging
6. Timeouts - Set appropriate timeout values
7. Retries - Implement retry logic for transient failures
8. Caching - Cache responses when appropriate

Troubleshooting

Use Cases

• Data Synchronization - Sync data from external systems
• Service Integration - Connect to SaaS platforms
• Automation - Automate cross-system workflows
• Monitoring - Poll external systems for changes
• Reporting - Aggregate data from multiple APIs

Related Templates

• Public APIs - Pre-built integrations for public APIs
• Bling ERP - ERP API integration example
• LLM Server - Building your own API endpoints
• CRM - CRM with external API sync

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Platform Analytics Template (analytics.gbai)

A General Bots template for platform metrics, performance monitoring, and custom report generation.

Overview

The Analytics template provides comprehensive platform analytics capabilities, allowing administrators and stakeholders to monitor usage, track performance, analyze trends, and generate custom reports through conversational AI.

Features

• Platform Overview - Key metrics summary with trend analysis
• Message Analytics - Conversation statistics by channel and bot
• User Analytics - Active users, sessions, and engagement
• Performance Metrics - Response times and throughput monitoring
• LLM Usage Tracking - Token consumption and cost analysis
• Storage Analytics - Disk usage and file statistics
• Error Analysis - Error patterns and troubleshooting insights
• Custom Report Generator - Build and schedule personalized reports
• AI-Powered Insights - Automatic trend analysis and recommendations

Package Structure

analytics.gbai/
├── analytics.gbdialog/
│   ├── start.bas              # Main menu and navigation
│   ├── platform-overview.bas  # Key metrics dashboard
│   └── custom-report.bas      # Custom report builder
└── analytics.gbot/
    └── config.csv             # Bot configuration

Scripts

Available Analytics

1. Platform Overview

High-level metrics summary including:

• Total messages and trend percentage
• Average active sessions
• Response time performance
• Error rates
• LLM token consumption

2. Message Analytics

• Message volume by time period
• Breakdown by channel (WhatsApp, Web, API)
• Bot-specific conversation stats
• Peak usage times

3. User Analytics

• Active users (daily, weekly, monthly)
• Session duration analysis
• User retention rates
• Geographic distribution

4. Performance Metrics

• Average response time
• Response time distribution
• Throughput (messages per second)
• Latency percentiles (p50, p95, p99)

5. LLM Usage

• Token consumption by model
• Cost analysis
• Usage patterns
• Optimization recommendations

6. Storage Analytics

• Disk usage trends
• File count and types
• Storage by bot/package
• Cleanup recommendations

7. Error Analysis

• Error frequency and patterns
• Error categorization
• Root cause analysis
• Resolution suggestions

8. Custom Reports

• Select metrics to include
• Choose time ranges
• Set grouping intervals
• Export in multiple formats
• Schedule automatic delivery

Sample Conversation

User: Show me analytics

Bot:  Welcome to the Analytics Center. I can help you 
      understand your platform metrics and generate reports.

      What would you like to analyze?
      1. Platform Overview - Key metrics summary
      2. Message Analytics - Conversation statistics
      3. User Analytics - Active users and sessions
      4. Performance Metrics - Response times
      5. LLM Usage - Token consumption and costs
      6. Storage Analytics - Disk usage
      7. Error Analysis - Error patterns
      8. Generate Custom Report

User: 1

Bot:  Generating platform overview...
      Select time range (1h, 6h, 24h, 7d, 30d):

User: 24h

Bot:  📊 Platform Overview for Last 24 Hours
      ════════════════════════════════════════
      
      📨 Messages
         Total: 15,432
         Trend: ▲ +12.5% vs previous period
      
      👥 Sessions
         Average Active: 234
         Peak: 412 (at 2:30 PM)
         Trend: ▲ +5.2%
      
      ⚡ Performance
         Avg Response Time: 145 ms
         P95: 320 ms
         P99: 580 ms
      
      ❌ Errors
         Total: 23
         Error Rate: 0.15%
         Most Common: Timeout (12)
      
      🤖 LLM Usage
         Total Tokens: 1,245,678
         Estimated Cost: $18.45
         Avg per Message: 81 tokens
      
      Would you like to:
      (D)etail, (E)xport report, (A)lerts, (B)ack

User: E

Bot:  Export format (PDF, CSV, XLSX):

User: PDF

Bot:  ✅ Report exported: platform_overview_20240515.pdf
      
      The file is available in your Drive.
      Download link: [secure link]

Custom Report Generation

User: I need a custom report

Bot:  Custom Report Generator
      What would you like to name this report?

User: Weekly Performance Summary

Bot:  Select the time range:
      1. Last Hour
      2. Last 24 Hours
      3. Last 7 Days
      4. Last 30 Days
      5. Custom Range

User: 3

Bot:  Select metrics to include (comma-separated):
      1. Message Volume
      2. Active Sessions
      3. Response Time
      4. LLM Token Usage
      5. Error Rate
      6. Storage Usage
      7. API Calls
      8. User Activity
      9. Bot Performance
      10. All Metrics

User: 1,3,4,5

Bot:  Select grouping interval:
      1. Hourly
      2. Daily
      3. Weekly

User: 2

Bot:  Generating your custom report...
      
      ✅ Report generated successfully!
      
      📋 Weekly Performance Summary
      📅 Period: May 8-15, 2025
      📊 Metrics: Messages, Response Time, LLM Usage, Errors
      📈 Grouping: Daily
      
      Download: [secure link]
      
      Would you like to schedule this report?

User: Yes, weekly

Bot:  ✅ Report scheduled!
      
      Frequency: Weekly on Monday at 8:00 AM
      Delivery: Email to your address
      
      You can manage scheduled reports anytime.

Metrics Query System

The template uses a metrics query system:

' Query metrics for a time range
messages = QUERY METRICS "messages" FOR "24h"
totalMessages = SUM(messages, "count")

' Query with grouping
hourlyMessages = QUERY METRICS "messages" FOR "24h" BY "1h"

' Query with offset for comparison
prevMessages = QUERY METRICS "messages" FOR "24h" OFFSET 1
trend = ((totalMessages - SUM(prevMessages, "count")) / SUM(prevMessages, "count")) * 100

Export Formats

Reports can be exported in multiple formats:

Scheduled Reports

Configure automatic report delivery:

SET SCHEDULE "0 8 * * 1", "generate-scheduled-report.bas"

Configuration

Configure in analytics.gbot/config.csv:

Customization

Adding Custom Metrics

' Track custom events
INSERT INTO "custom_metrics" VALUES {
    "name": "feature_usage",
    "value": 1,
    "tags": {"feature": "chat", "plan": "pro"},
    "timestamp": NOW()
}

' Query custom metrics
usage = QUERY METRICS "feature_usage" FOR "30d" WHERE tags.feature = "chat"

Custom Dashboard Widgets

' Add to start.bas
TALK "Custom Metrics:"
TALK "9. Feature Usage"
TALK "10. Revenue Analytics"
TALK "11. Customer Health Score"

' Handle custom options
CASE 9
    CALL "feature-usage.bas"
CASE 10
    CALL "revenue-analytics.bas"

AI-Powered Insights

' Generate AI insights from metrics
SET CONTEXT "You are an analytics expert. Generate executive insights."

insights = LLM "Analyze this data and provide 3-5 key insights: " + JSON(report_data)

Integration Examples

With Alerting

' Set up alerts based on metrics
errorRate = SUM(errors, "count") / SUM(messages, "count") * 100

IF errorRate > 5 THEN
    SEND MAIL admin_email, "High Error Rate Alert", 
        "Error rate is " + errorRate + "%, above 5% threshold.", []
END IF

With External BI Tools

' Export data for external tools
data = QUERY METRICS "messages" FOR "30d" BY "1d"
WRITE "analytics_export.csv", CSV(data)

' Or send to webhook
POST "https://bi-tool.example.com/webhook", data

Best Practices

1. Set appropriate time ranges - Don’t query more data than needed
2. Use caching - Cache expensive queries
3. Schedule off-peak - Run heavy reports during low traffic
4. Monitor the monitor - Track analytics query performance
5. Archive old data - Move historical data to cold storage
6. Validate insights - Review AI-generated insights for accuracy

Troubleshooting

Use Cases

• Operations Teams - Monitor platform health and performance
• Product Managers - Track feature usage and engagement
• Executives - High-level KPI dashboards
• Support Teams - Identify error patterns
• Finance - LLM cost tracking and optimization

Data Privacy

• Analytics data is aggregated and anonymized
• User-level data requires appropriate permissions
• Respect data retention policies
• Comply with GDPR/CCPA as applicable

Related Templates

• BI Template - Business Intelligence reporting
• Talk to Data - Natural language data queries
• CRM - CRM analytics and pipeline reports

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Office Automation Template (office.gbai)

A General Bots template for role-based office productivity with department-specific knowledge bases and context-aware assistance.

Overview

The Office template provides a multi-role office assistant that adapts its behavior, knowledge, and suggestions based on the user’s role. Whether you’re a manager, developer, customer support agent, HR professional, or finance team member, the bot tailors its responses and available resources accordingly.

Features

• Role-Based Access - Different capabilities per user role
• Dynamic Knowledge Bases - Automatically loads relevant KB per role
• Context-Aware Responses - AI behavior adapts to role requirements
• Custom Suggestions - Role-specific quick actions
• Tool Integration - Calendar, tasks, documents, meetings, notes
• Persistent Role Memory - Remembers user role across sessions

Package Structure

office.gbai/
├── office.gbdialog/
│   ├── start.bas               # Role selection and configuration
│   ├── api-integration.bas     # External API connections
│   ├── data-sync.bas           # Data synchronization
│   └── document-processor.bas  # Document handling
├── office.gbkb/                # Knowledge bases by role
│   ├── management/
│   ├── documentation/
│   ├── products/
│   ├── hr-policies/
│   └── budgets/
└── office.gbot/
    └── config.csv              # Bot configuration

Scripts

Supported Roles

Manager

• Context: Executive assistant for reports, team management, strategic decisions
• Knowledge Bases: management, reports, team-policies
• Suggestions: Team performance, Generate report, Schedule meeting

Developer

• Context: Technical assistant for documentation, APIs, coding best practices
• Knowledge Bases: documentation, apis, coding-standards
• Suggestions: Search documentation, API reference, Code review checklist

Customer Support

• Context: Customer service assistant focused on resolving issues
• Knowledge Bases: products, support, faq
• Suggestions: Track my order, Product information, Contact support

HR

• Context: HR assistant for employee matters, policies, benefits
• Knowledge Bases: hr-policies, benefits, onboarding
• Suggestions: Employee handbook, Benefits overview, New hire checklist

Finance

• Context: Finance assistant for budgets, expenses, financial reports
• Knowledge Bases: budgets, expenses, financial-reports
• Suggestions: Expense policy, Budget status, Approval workflow

Available Tools

Sample Conversation

Role Selection

Bot:  Welcome to the Office Assistant!
      Please select your role:

User: manager

Bot:  Welcome, Manager! I can help with reports, team 
      management, and policies.
      
      Quick Actions:
      • Team performance
      • Generate report
      • Schedule meeting

Manager Interaction

User: I need to review my team's performance

Bot:  I'll help you review team performance. Here's a summary:

      📊 Team Performance Dashboard
      
      Active Projects: 5
      Completed This Month: 3
      
      Top Performers:
      • Sarah Chen: 12 tasks completed
      • Mike Johnson: 10 tasks completed
      
      Pending Approvals: 2
      
      Would you like a detailed report or to schedule 1:1s?

Developer Interaction

User: How do I implement pagination in our API?

Bot:  Based on our API documentation, here's the pagination pattern:

      GET /api/v1/users?page=1&per_page=20
      
      Response includes:
      • data: Array of results
      • meta.total: Total count
      • meta.page: Current page
      • links.next: Next page URL
      
      Our coding standards recommend cursor-based pagination 
      for large datasets.
      
      📄 Source: docs/api/pagination.md

Customer Support Interaction

User: Customer asking about order #12345

Bot:  I found order #12345. Here are the details:
      
      📦 Order Status: Shipped
      📅 Shipped: May 14, 2025
      🚚 Carrier: FedEx
      📍 Tracking: 7891234567890
      
      Expected delivery: May 17, 2025
      
      Would you like to:
      • Send tracking info to customer
      • Create a support ticket
      • Escalate to supervisor

Configuration

Configure in office.gbot/config.csv:

How It Works

Role Detection and Setup

ADD TOOL "calendar"
ADD TOOL "tasks"
ADD TOOL "documents"
ADD TOOL "meetings"
ADD TOOL "notes"

role = GET role

IF NOT role THEN
    TALK "Welcome to the Office Assistant!"
    TALK "Please select your role:"
    HEAR role AS NAME
    role = LOWER(role)
    SET role, role
END IF

SWITCH role
  CASE "manager"
    SET CONTEXT "You are an executive assistant helping managers..."
    USE KB "management"
    USE KB "reports"
    USE KB "team-policies"
    TALK "Welcome, Manager! I can help with reports and team management."

  CASE "developer"
    SET CONTEXT "You are a technical assistant helping developers..."
    USE KB "documentation"
    USE KB "apis"
    USE KB "coding-standards"
    TALK "Welcome, Developer! I can help with documentation and APIs."

  ' ... more roles
END SWITCH

Dynamic Suggestions

CLEAR SUGGESTIONS

SWITCH role
  CASE "manager"
    ADD SUGGESTION "performance" AS "Team performance"
    ADD SUGGESTION "report" AS "Generate report"
    ADD SUGGESTION "meeting" AS "Schedule meeting"

  CASE "developer"
    ADD SUGGESTION "docs" AS "Search documentation"
    ADD SUGGESTION "api" AS "API reference"
    ADD SUGGESTION "review" AS "Code review checklist"

  CASE "customer"
    ADD SUGGESTION "order" AS "Track my order"
    ADD SUGGESTION "product" AS "Product information"
    ADD SUGGESTION "support" AS "Contact support"
END SWITCH

Customization

Adding New Roles

Extend the start.bas file:

CASE "sales"
    SET CONTEXT "You are a sales assistant helping with leads and deals."
    USE KB "sales-playbook"
    USE KB "pricing"
    USE KB "competitors"
    TALK "Welcome, Sales! I can help with leads, pricing, and proposals."

    CLEAR SUGGESTIONS
    ADD SUGGESTION "leads" AS "View my leads"
    ADD SUGGESTION "quote" AS "Generate quote"
    ADD SUGGESTION "pipeline" AS "Pipeline status"

Custom Knowledge Bases

Create role-specific knowledge bases in office.gbkb/:

office.gbkb/
├── sales-playbook/
│   ├── objection-handling.md
│   ├── pricing-guide.md
│   └── competitor-comparison.md

Role-Specific Tools

Register different tools per role:

CASE "manager"
    ADD TOOL "calendar"
    ADD TOOL "tasks"
    ADD TOOL "team-report"
    ADD TOOL "approve-request"

CASE "developer"
    ADD TOOL "search-docs"
    ADD TOOL "api-tester"
    ADD TOOL "code-review"

Integration Examples

With Calendar

' Schedule meeting for manager
IF role = "manager" THEN
    TALK "I'll schedule the team meeting."
    CREATE CALENDAR EVENT "Team Standup", tomorrow + " 9:00 AM", 30
END IF

With Document System

' Generate document based on role
SWITCH role
    CASE "hr"
        template = "offer-letter-template.docx"
    CASE "sales"
        template = "proposal-template.docx"
    CASE "finance"
        template = "budget-template.xlsx"
END SWITCH

document = GENERATE FROM TEMPLATE template WITH data

With Task Management

' Create role-appropriate tasks
IF role = "manager" THEN
    CREATE TASK "Review Q4 budget", "high", manager_email
    CREATE TASK "Approve team PTO requests", "medium", manager_email
END IF

Best Practices

1. Clear role definitions - Define clear boundaries for each role
2. Relevant suggestions - Keep quick actions useful for each role
3. Appropriate KBs - Only load necessary knowledge bases
4. Security awareness - Restrict sensitive data by role
5. Regular updates - Keep knowledge bases current
6. Feedback loops - Monitor which features each role uses

Troubleshooting

Use Cases

• Corporate Offices - Multi-department support
• Startups - Flexible role-based assistance
• Remote Teams - Unified office assistant
• Enterprise - Department-specific knowledge management

Related Templates

• Contacts - Contact management
• Reminder - Task and reminder management
• CRM - Full CRM for sales roles
• Analytics - Platform analytics for managers

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Reminder Template (reminder.gbai)

A General Bots template for managing personal and team reminders with multi-channel notifications.

Overview

The Reminder template provides a complete reminder management system with natural language scheduling, multiple notification channels, and snooze capabilities. Users can create, view, manage, and receive reminders through conversational AI.

Features

• Natural Language Scheduling - Create reminders using everyday language
• Multi-Channel Notifications - Email, SMS, or chat notifications
• Reminder Management - List, snooze, and delete reminders
• Scheduled Execution - Background job checks and sends due reminders
• Smart Date Parsing - Understands “tomorrow”, “next week”, “in 2 hours”
• Persistent Storage - Reminders saved to CSV for reliability

Package Structure

reminder.gbai/
├── reminder.gbdata/           # Data storage
│   └── reminders.csv          # Reminder records
├── reminder.gbdialog/
│   ├── start.bas              # Main entry and tool registration
│   ├── add-reminder.bas       # Create new reminders
│   └── reminder.bas           # Scheduled job to send reminders
└── reminder.gbot/
    └── config.csv             # Bot configuration

Scripts

Available Tools

Data Schema

Reminders Table

Sample Conversation

Creating Reminders

User: Remind me to call John tomorrow at 9am

Bot:  ✅ Reminder set: Call John
      When: Tomorrow at 9:00 AM
      Notification: chat

User: Set a reminder for next Monday at 2pm to submit the report

Bot:  ✅ Reminder set: Submit the report
      When: Monday, May 19 at 2:00 PM
      Notification: chat

User: In 30 minutes remind me to take a break

Bot:  ✅ Reminder set: Take a break
      When: in 30 minutes (2:45 PM)
      Notification: chat

Viewing Reminders

User: Show my reminders

Bot:  📋 Your Reminders:

      1. Call John
         📅 Tomorrow at 9:00 AM
         🔔 chat
         
      2. Submit the report
         📅 Monday, May 19 at 2:00 PM
         🔔 chat
         
      3. Take a break
         📅 Today at 2:45 PM
         🔔 chat

Managing Reminders

User: Snooze my call reminder for 1 hour

Bot:  ✅ Reminder snoozed. New time: Tomorrow at 10:00 AM

User: Delete the report reminder

Bot:  ✅ Reminder deleted: Submit the report

How It Works

Tool Registration

ADD TOOL "add-reminder"
ADD TOOL "list-reminders"
ADD TOOL "delete-reminder"
ADD TOOL "snooze-reminder"

USE KB "reminder.gbkb"

CLEAR SUGGESTIONS

ADD SUGGESTION "add" AS "Add a reminder"
ADD SUGGESTION "list" AS "View my reminders"
ADD SUGGESTION "today" AS "Today's reminders"
ADD SUGGESTION "delete" AS "Delete a reminder"

SET CONTEXT "reminders" AS "You are a reminder assistant helping users manage their tasks and reminders."

BEGIN SYSTEM PROMPT
You are a reminder AI assistant.

When creating reminders:
- Parse natural language dates (tomorrow, next week, in 2 hours)
- Confirm the reminder details before saving
- Suggest appropriate times if not specified

When listing reminders:
- Show upcoming reminders first
- Highlight overdue items
- Group by date when appropriate

Be concise and helpful.
END SYSTEM PROMPT

Creating Reminders

' add-reminder.bas
PARAM when AS STRING LIKE "tomorrow at 9am" DESCRIPTION "When to send the reminder"
PARAM subject AS STRING LIKE "Call John" DESCRIPTION "What to be reminded about"
PARAM notify AS STRING LIKE "email" DESCRIPTION "Notification method" OPTIONAL

DESCRIPTION "Create a reminder for a specific date and time"

IF NOT notify THEN
    notify = "chat"
END IF

reminderid = "REM-" + FORMAT(NOW(), "YYYYMMDD") + "-" + FORMAT(RANDOM(1000, 9999))
useremail = GET "session.user_email"
userphone = GET "session.user_phone"

WITH reminder
    id = reminderid
    remindAt = when
    message = subject
    notifyBy = notify
    email = useremail
    phone = userphone
    created = NOW()
    status = "pending"
END WITH

SAVE "reminders.csv", reminder

SET BOT MEMORY "last_reminder", reminderid

TALK "Reminder set: " + subject
TALK "When: " + when
TALK "Notification: " + notify

RETURN reminderid

Scheduled Reminder Delivery

' reminder.bas - runs on schedule
REM SET SCHEDULER "1 * * * * "

data = FIND "reminder.csv", "when=" + hour

IF data THEN
    TALK TO admin, data.subject
END IF

Notification Channels

Configuration

Configure in reminder.gbot/config.csv:

Customization

Custom Notification Channels

Add new notification types:

' In add-reminder.bas
SWITCH notify
    CASE "chat"
        ' Default chat notification
    CASE "email"
        SEND MAIL email, "Reminder: " + subject, message, []
    CASE "sms"
        SEND SMS phone, "Reminder: " + subject
    CASE "slack"
        POST "https://hooks.slack.com/...", {"text": "Reminder: " + subject}
    CASE "teams"
        POST "https://outlook.office.com/webhook/...", {"text": subject}
END SWITCH

Recurring Reminders

Add support for recurring reminders:

' add-recurring-reminder.bas
PARAM subject AS STRING DESCRIPTION "What to remind about"
PARAM schedule AS STRING LIKE "daily" DESCRIPTION "Frequency: daily, weekly, monthly"
PARAM time AS STRING LIKE "9:00 AM" DESCRIPTION "Time of day"

DESCRIPTION "Create a recurring reminder"

SET SCHEDULE cron_expression, "send-recurring.bas"

WITH reminder
    id = "REC-" + FORMAT(GUID())
    message = subject
    frequency = schedule
    remindTime = time
    status = "active"
END WITH

SAVE "recurring_reminders.csv", reminder

Priority Levels

Add priority support:

PARAM priority AS STRING LIKE "high" DESCRIPTION "Priority: low, medium, high" OPTIONAL

IF priority = "high" THEN
    ' Send via multiple channels
    SEND MAIL email, "🔴 URGENT: " + subject, message, []
    SEND SMS phone, "URGENT: " + subject
END IF

Integration Examples

With Calendar

' Sync reminder to calendar
IF reminder.notifyBy = "calendar" THEN
    CREATE CALENDAR EVENT reminder.message, reminder.remindAt, 15
END IF

With Tasks

' Convert reminder to task when due
IF reminder.status = "sent" THEN
    CREATE TASK reminder.message, "medium", user_email
END IF

With CRM

' Add follow-up reminder from CRM
PARAM contact_id AS STRING DESCRIPTION "Contact to follow up with"
PARAM days AS INTEGER LIKE 7 DESCRIPTION "Days until follow-up"

contact = FIND "contacts.csv", "id = " + contact_id

WITH reminder
    id = FORMAT(GUID())
    message = "Follow up with " + contact.name
    remindAt = DATEADD(NOW(), days, "day")
    notifyBy = "chat"
    relatedTo = contact_id
END WITH

SAVE "reminders.csv", reminder

Date Parsing Examples

The LLM understands various date formats:

Best Practices

1. Be specific - Include enough detail in reminder messages
2. Set appropriate times - Don’t set reminders for odd hours
3. Use the right channel - Critical reminders via multiple channels
4. Clean up - Delete completed reminders regularly
5. Review regularly - Check reminder list to stay organized
6. Test notifications - Verify each channel works before relying on it

Troubleshooting

Use Cases

• Personal Productivity - Don’t forget important tasks
• Team Coordination - Remind team members of deadlines
• Customer Follow-ups - Schedule sales and support follow-ups
• Meeting Prep - Get reminded before meetings
• Health & Wellness - Regular break and wellness reminders

Related Templates

• Office - Office productivity with task management
• CRM - CRM with follow-up reminders
• Contacts - Contact management with activity tracking
• Marketing - Marketing with scheduled broadcasts

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

Sales CRM Template (crm.gbai)

A comprehensive General Bots template for sales customer relationship management with lead tracking, opportunity management, and sales pipeline automation.

Overview

The CRM template provides a full-featured sales CRM system with conversational AI capabilities. It enables sales teams to manage leads, track opportunities through the pipeline, generate quotes, send proposals, and forecast revenue—all through natural conversation or automated workflows.

Features

• Lead Management - Capture, qualify, convert, and nurture leads
• Opportunity Pipeline - Track deals through customizable stages
• Account Management - Manage customer accounts and contacts
• Activity Tracking - Log calls, emails, meetings, and tasks
• Quote Generation - Create and send professional quotes
• Proposal Automation - Generate and deliver sales proposals
• Sales Forecasting - Pipeline analysis and revenue projections
• Email Integration - Receive and process emails automatically
• Sentiment Analysis - AI-powered customer sentiment tracking
• Data Enrichment - Automatic lead data enhancement

Package Structure

crm.gbai/
├── crm.gbdialog/
│   ├── lead-management.bas          # Lead lifecycle management
│   ├── opportunity-management.bas   # Opportunity pipeline
│   ├── account-management.bas       # Account/company management
│   ├── activity-tracking.bas        # Activity logging
│   ├── case-management.bas          # Support case handling
│   ├── analyze-customer-sentiment.bas # AI sentiment analysis
│   ├── data-enrichment.bas          # Lead data enhancement
│   ├── send-proposal.bas            # Proposal generation
│   ├── create-lead-from-draft.bas   # Email to lead conversion
│   ├── crm-jobs.bas                 # Scheduled background jobs
│   └── tables.bas                   # Database schema definitions
└── crm.gbot/
    └── config.csv                   # Bot configuration

Scripts

Data Schema

Leads Table

Opportunities Table

Accounts Table

Contacts Table

Activities Table

Pipeline Stages

Sample Conversations

Lead Capture

User: I just got a lead from the website

Bot:  Great! I'll help you capture it. What's their name?

User: John Smith from TechCorp

Bot:  What's their email?

User: john@techcorp.com

Bot:  ✅ Lead captured: John Smith (TechCorp)
      ID: LEAD-20240115-4821
      
      Would you like to qualify this lead now?

Lead Qualification (BANT)

User: Yes, qualify the lead

Bot:  I'll ask a few questions to qualify them.
      
      What is TechCorp's annual revenue range?
      1. Under $1M
      2. $1M - $10M
      3. $10M - $50M
      4. Over $50M

User: 3

Bot:  How many employees?

User: About 200

Bot:  What's their timeline for making a decision?

User: This quarter

Bot:  Do they have budget allocated?

User: Yes

Bot:  🔥 Hot Lead! Score: 85/100
      
      This lead is a great fit. I've:
      • Notified sales@company.com
      • Created a follow-up task
      
      Would you like to convert to an opportunity?

Opportunity Management

User: Create a new opportunity for Acme Corp

Bot:  What should we call this opportunity?

User: Enterprise License Deal

Bot:  What is the estimated value of this deal?

User: $50,000

Bot:  When do you expect to close this deal?

User: End of Q2

Bot:  ✅ Opportunity created: Enterprise License Deal
      
      Account: Acme Corp
      Value: $50,000
      Stage: Qualification (10%)
      Close Date: June 30, 2024

Pipeline Update

User: Update the Acme deal to proposal stage

Bot:  Current stage: value_proposition
      
      Select new stage:
      1. Qualification (10%)
      2. Needs Analysis (20%)
      3. Value Proposition (50%)
      4. Decision Makers (60%)
      5. Proposal (75%)
      6. Negotiation (90%)
      7. Closed Won (100%)
      8. Closed Lost (0%)

User: 5

Bot:  ✅ Stage updated to proposal (75%)
      
      Would you like to generate a quote for this opportunity?

Sales Forecast

User: Show me the sales forecast

Bot:  📊 SALES FORECAST
      ════════════════════════════════════════
      
      Total Pipeline: $425,000
      Weighted Pipeline: $187,500
      
      Quarterly Forecast:
      ├── Q1: $45,000
      ├── Q2: $82,500
      ├── Q3: $35,000
      └── Q4: $25,000
      
      Top Opportunities:
      1. Enterprise License - Acme Corp ($50,000) - 75%
      2. Platform Upgrade - TechStart ($35,000) - 60%
      3. Consulting Deal - DataFlow ($28,000) - 50%

Lead Qualification Scoring

The qualification process scores leads based on BANT criteria:

• Budget - Revenue range (up to 30 points)
• Authority - Employee count/company size (up to 25 points)
• Need - Timeline urgency (up to 30 points)
• Timeline - Budget allocation (up to 25 points)

Scoring Thresholds

Lead Nurturing

Automated nurture campaigns based on lead age:

Configuration

Configure in crm.gbot/config.csv:

Scheduled Jobs

Email Integration

Receiving Emails

' on-receive-email.bas
email_from = GET "email.from"
email_subject = GET "email.subject"
email_body = GET "email.body"

' Check if from existing contact
contact = FIND "contacts.csv", "email = '" + email_from + "'"

IF contact THEN
    ' Log activity against contact
    WITH activity
        type = "email"
        subject = email_subject
        contact_id = contact.id
    END WITH
    SAVE "activities.csv", activity
ELSE
    ' Create new lead from email
    CALL "create-lead-from-draft.bas"
END IF

Sending Proposals

' send-proposal.bas
proposal = GENERATE FROM TEMPLATE "proposal_template.docx" WITH {
    "company": account.name,
    "contact": contact.name,
    "products": opportunity_products,
    "total": quote.total,
    "valid_until": quote.valid_until
}

SEND MAIL contact.email, "Proposal: " + opportunity.name, 
    "Please find attached our proposal.", [proposal]

AI Features

Customer Sentiment Analysis

' analyze-customer-sentiment.bas
SET CONTEXT "Analyze customer communication for sentiment and buying signals."

communications = FIND "activities.csv", "contact_id = '" + contact_id + "'"

analysis = LLM "Analyze these customer communications and provide:
               1. Overall sentiment (positive, neutral, negative)
               2. Buying signals detected
               3. Concerns or objections
               4. Recommended next action
               
               Communications: " + JSON(communications)

TALK analysis

Data Enrichment

' data-enrichment.bas
' Enrich lead with external data
company_info = GET "https://api.enrichment.com/company/" + lead.company

IF company_info THEN
    lead.industry = company_info.industry
    lead.employee_count = company_info.employees
    lead.revenue_range = company_info.revenue
    lead.linkedin_url = company_info.linkedin
    
    UPDATE "leads.csv", lead
END IF

Best Practices

1. Qualify early - Use BANT scoring to prioritize leads
2. Track everything - Log all customer interactions
3. Follow up promptly - Hot leads within hours, warm within 24h
4. Use automation - Let nurture campaigns work cold leads
5. Clean pipeline - Archive stale opportunities regularly
6. Forecast accurately - Keep close dates and probabilities updated
7. Segment leads - Use tags and sources for better targeting

Troubleshooting

Use Cases

• Inside Sales - Lead qualification and opportunity management
• Field Sales - Account management and activity tracking
• Sales Management - Pipeline visibility and forecasting
• Business Development - Lead generation and nurturing
• Customer Success - Account health and expansion opportunities

Integration Points

• Email - Inbound/outbound email tracking
• Calendar - Meeting scheduling
• ERP - Order and billing sync
• Marketing Automation - Lead handoff
• Support Ticketing - Case management

Related Templates

• Contacts - Contact directory management
• Marketing - Marketing automation and campaigns
• Analytics - Sales analytics and reporting
• Reminder - Follow-up reminders

See Also

• Templates Reference - Full template list
• Template Samples - Example conversations
• gbdialog Reference - BASIC scripting guide

CRM Contacts Template

The CRM Contacts template provides a complete contact management solution with natural language interface. Users can add, search, update, and manage contacts through conversational interactions.

Overview

Features

• Add new contacts with validation
• Search contacts by name, email, or phone
• Update contact information
• Tag and categorize contacts
• Export contacts to CSV

Installation

Copy the template folder to your work directory or use the Sources app to create from template.

Configuration

Add these settings to your config.csv:

Sample Conversations

Adding a New Contact

Searching Contacts

Updating a Contact

Exporting Contacts

What It Can Do

Customization Ideas

Add Custom Fields

Configure additional fields like LinkedIn profile, job title, or lead source in your bot’s config.csv.

Add Validation

The bot validates email formats and phone numbers automatically. Configure stricter rules as needed.

Connect to External CRM

Use the POST and GET keywords to sync contacts with Salesforce, HubSpot, or other CRM systems.

Related Templates

• Sales Pipeline - Track deals and opportunities
• Customer Support - Support ticket management
• Template Samples - More conversation examples

Attendance CRM Template (attendance-crm.gbai)

A hybrid AI + Human support template that combines intelligent bot routing with human attendant management and full CRM automation. This template demonstrates the power of General Bots as an LLM orchestrator for customer service operations.

Overview

The Attendance CRM template provides:

• Intelligent Routing - Bot analyzes sentiment and auto-transfers frustrated customers
• LLM-Assisted Attendants - AI tips, message polish, smart replies for human agents
• Queue Management - Automated queue monitoring and load balancing
• CRM Automations - Follow-ups, collections, lead nurturing, pipeline management
• Multi-Channel Support - Works on WhatsApp, Web, and other channels

Key Features

Package Structure

attendance-crm.gbai/
├── attendance-crm.gbdialog/
│   ├── start.bas                 # Main entry - intelligent routing
│   ├── queue-monitor.bas         # Queue health monitoring (scheduled)
│   ├── attendant-helper.bas      # LLM assist tools for attendants
│   └── crm-automations.bas       # Follow-ups, collections, nurturing
├── attendance-crm.gbot/
│   └── config.csv                # Bot configuration
└── attendant.csv                 # Attendant team configuration

Configuration

config.csv

name,value

# Bot Identity
bot-name,Attendance CRM Bot
bot-description,Hybrid AI + Human support with CRM integration

# CRM / Human Handoff - Required
crm-enabled,true

# LLM Assist Features for Attendants
attendant-llm-tips,true
attendant-polish-message,true
attendant-smart-replies,true
attendant-auto-summary,true
attendant-sentiment-analysis,true

# Bot Personality (used for LLM assist context)
bot-system-prompt,You are a professional customer service assistant. Be helpful and empathetic.

# Auto-transfer triggers
auto-transfer-on-frustration,true
auto-transfer-threshold,3

# Queue Settings
queue-timeout-minutes,30
queue-notify-interval,5

# Lead Scoring
lead-score-threshold-hot,70
lead-score-threshold-warm,50

# Follow-up Automation
follow-up-1-day,true
follow-up-3-day,true
follow-up-7-day,true

# Collections Automation
collections-enabled,true
collections-grace-days,3

# Working Hours
business-hours-start,09:00
business-hours-end,18:00
business-days,1-5

# Notifications
notify-on-vip,true
notify-on-escalation,true
notify-email,support@company.com

attendant.csv

Attendants can be identified by any channel: WhatsApp phone, email, Microsoft Teams, or Google account.

id,name,channel,preferences,department,aliases,phone,email,teams,google
att-001,João Silva,all,sales,commercial,joao;js;silva,+5511999990001,joao.silva@company.com,joao.silva@company.onmicrosoft.com,joao.silva@company.com
att-002,Maria Santos,whatsapp,support,customer-service,maria;ms,+5511999990002,maria.santos@company.com,maria.santos@company.onmicrosoft.com,maria.santos@gmail.com
att-003,Pedro Costa,web,technical,engineering,pedro;pc;tech,+5511999990003,pedro.costa@company.com,pedro.costa@company.onmicrosoft.com,pedro.costa@company.com
att-004,Ana Oliveira,all,collections,finance,ana;ao;cobranca,+5511999990004,ana.oliveira@company.com,ana.oliveira@company.onmicrosoft.com,ana.oliveira@company.com
att-005,Carlos Souza,whatsapp,sales,commercial,carlos;cs,+5511999990005,carlos.souza@company.com,carlos.souza@company.onmicrosoft.com,carlos.souza@gmail.com

Column Reference

The system can find an attendant by any identifier - phone, email, Teams UPN, Google account, name, or alias.

---

## Scripts

### start.bas - Intelligent Routing

The main entry point analyzes every customer message and decides routing:

```basic
' Analyze sentiment immediately
sentiment = ANALYZE SENTIMENT session.id, message

' Track frustration
IF sentiment.overall = "negative" THEN
    frustration_count = frustration_count + 1
END IF

' Auto-transfer on high escalation risk
IF sentiment.escalation_risk = "high" THEN
    tips = GET TIPS session.id, message
    result = TRANSFER TO HUMAN "support", "urgent", context_summary
END IF

Key behaviors:

• Analyzes sentiment on every message
• Tracks frustration count across conversation
• Auto-transfers on explicit request (“falar com humano”, “talk to human”)
• Auto-transfers when escalation risk is high
• Auto-transfers after 3+ negative messages
• Passes AI tips to attendant during transfer

queue-monitor.bas - Queue Health

Scheduled job that runs every 5 minutes:

SET SCHEDULE "queue-monitor", "*/5 * * * *"

What it does:

• Finds conversations waiting >10 minutes → auto-assigns
• Finds inactive assigned conversations → reminds attendant
• Finds conversations with offline attendants → reassigns
• Detects abandoned conversations → sends follow-up, then resolves
• Generates queue metrics for dashboard
• Alerts supervisor if queue gets long or no attendants online

attendant-helper.bas - LLM Assist Tools

Provides AI-powered assistance to human attendants:

' Get tips for current conversation
tips = USE TOOL "attendant-helper", "tips", session_id, message

' Polish a message before sending
polished = USE TOOL "attendant-helper", "polish", session_id, message, "empathetic"

' Get smart reply suggestions
replies = USE TOOL "attendant-helper", "replies", session_id

' Get conversation summary
summary = USE TOOL "attendant-helper", "summary", session_id

' Analyze sentiment with recommendations
sentiment = USE TOOL "attendant-helper", "sentiment", session_id, message

' Check if transfer is recommended
should_transfer = USE TOOL "attendant-helper", "suggest_transfer", session_id

crm-automations.bas - Business Workflows

Scheduled CRM automations:

' Daily follow-ups at 9am weekdays
SET SCHEDULE "follow-ups", "0 9 * * 1-5"

' Daily collections at 8am weekdays
SET SCHEDULE "collections", "0 8 * * 1-5"

' Daily lead nurturing at 10am weekdays
SET SCHEDULE "lead-nurture", "0 10 * * 1-5"

' Weekly pipeline review Friday 2pm
SET SCHEDULE "pipeline-review", "0 14 * * 5"

BASIC Keywords Used

Queue Management

Attendant Management

LLM Assist

Customer Journey

Sample Conversations

Auto-Transfer on Frustration

Customer: Olá, preciso de ajuda com meu pedido

Bot: Olá! Claro, ficarei feliz em ajudar com seu pedido.
     Qual é o número do pedido?

Customer: #12345

Bot: Encontrei seu pedido #12345. Está em trânsito e deve
     chegar amanhã. Posso ajudar com mais alguma coisa?

Customer: Amanhã?! Isso é ridículo! Já deveria ter chegado há 3 dias!

Bot: [Sentiment: negative, Escalation Risk: medium]
     Entendo sua frustração. Peço desculpas pelo atraso.
     Se preferir falar com um atendente humano, é só me avisar.

Customer: SIM! Quero falar com alguém de verdade AGORA!

Bot: [Auto-transfer triggered]
     Estou transferindo você para Maria Santos.
     Um momento, por favor.

     [Tips sent to Maria:]
     ⚠️ Customer frustrated - 3 negative messages
     🎯 Issue: Delayed order #12345
     ✅ Offer compensation for delay

Attendant Using LLM Assist

[Customer message arrives]
Customer: não consigo acessar minha conta faz 2 dias!!

[AI Tips appear in attendant UI:]
💡 Tips:
   ⚠️ Customer frustrated - use empathetic tone
   🎯 Intent: Account access issue
   ✅ Verify account status, offer password reset

[Attendant types response:]
Attendant: oi, vou verificar sua conta

[Clicks ✨ Polish button:]
Polished: "Olá! Entendo como isso pode ser frustrante.
          Vou verificar sua conta agora mesmo e resolver
          isso para você."

[Attendant sends polished message]

Automation Workflows

Follow-up Sequence

Collections Workflow

WhatsApp Templates Required

Configure these in Meta Business Manager:

Metrics & Analytics

The template automatically tracks:

• Queue Metrics: Wait times, queue length, utilization
• Attendant Performance: Resolved count, active conversations
• Sentiment Trends: Per conversation and overall
• Automation Results: Follow-ups sent, collections processed

Access via:

• Dashboard at /suite/analytics/
• API at /api/attendance/insights
• Stored in queue_metrics and automation_logs tables

Best Practices

1. Configure Sentiment Thresholds

Adjust auto-transfer-threshold based on your tolerance:

• 2 = Very aggressive (transfer quickly)
• 3 = Balanced (default)
• 5 = Conservative (try harder with bot)

2. Set Business Hours

Configure business-hours-* to avoid sending automated messages at night.

3. Train Your Team

Ensure attendants know the WhatsApp commands:

• /tips - Get AI tips
• /polish <message> - Improve message
• /replies - Get suggestions
• /resolve - Close conversation

4. Monitor Queue Health

Set up alerts for:

• Queue > 10 waiting
• No attendants online during business hours
• Average wait > 15 minutes

See Also

• Transfer to Human - Handoff details
• LLM-Assisted Attendant - AI copilot features
• Sales CRM Template - Full CRM without attendance
• Attendance Queue Module - Queue configuration

Marketing Automation Template (marketing.gbai)

A General Bots template for marketing campaign management, content creation, and multi-channel broadcast messaging.

Overview

The Marketing template provides marketing automation capabilities including campaign management, content ideation, image generation, social media posting, and WhatsApp broadcast messaging. It enables marketing teams to create, schedule, and deliver campaigns through conversational AI.

Features

• Campaign Management - Create and organize marketing campaigns
• Content Ideation - AI-assisted content idea generation
• Image Generation - AI-powered marketing visuals
• Social Media Posting - Direct posting to Instagram and other platforms
• WhatsApp Broadcasts - Mass messaging with template support
• Contact Segmentation - Target specific audience segments
• Template Compliance - META-approved template validation
• Broadcast Logging - Track delivery and engagement

Package Structure

marketing.gbai/
├── marketing.gbdialog/
│   ├── add-new-idea.bas       # Content ideation tool
│   ├── broadcast.bas          # WhatsApp broadcast messaging
│   ├── get-image.bas          # AI image generation
│   ├── post-to-instagram.bas  # Instagram posting
│   ├── poster.bas             # Marketing poster creation
│   └── campaigns/             # Campaign templates
└── marketing.gbot/
    └── config.csv             # Bot configuration

Scripts

WhatsApp Broadcast

The broadcast.bas script enables mass WhatsApp messaging with template support:

Parameters

Template Compliance

The system validates messages for META WhatsApp template approval:

report = LLM "Esta mensagem será aprovada pelo WhatsApp META como Template? 
              Responda OK se sim, ou explique o problema: " + message

IF report <> "OK" THEN
    TALK "Atenção: " + report
END IF

Broadcast Execution

IF filter THEN
    list = FIND list_file, filter
ELSE
    list = FIND list_file
END IF

index = 1
sent = 0

DO WHILE index < UBOUND(list)
    row = list[index]
    
    SEND TEMPLATE TO row.telefone, template_file
    
    WAIT 0.1  ' Rate limiting
    
    ' Log delivery
    WITH logEntry
        timestamp = NOW()
        phone = row.telefone
        name = row.name
        status = "sent"
    END WITH
    
    SAVE "broadcast_log.csv", logEntry
    
    sent = sent + 1
    index = index + 1
LOOP

TALK "Broadcast enviado para " + sent + " contatos."

Contact List Format

The contact file should include:

Example contacts.xlsx

telefone,name,email,Perfil
+5511999999999,João Silva,joao@email.com,VIP
+5511888888888,Maria Santos,maria@email.com,Regular
+5511777777777,Pedro Costa,pedro@email.com,VIP

Sample Conversations

Creating a Broadcast

User: Send a broadcast to VIP customers

Bot:  I'll help you create a broadcast. What's the message?

User: Olá {name}, aproveite 20% de desconto esta semana!

Bot:  Checking template compliance...
      ✅ Message approved for WhatsApp template.
      
      Do you have a header image?

User: Yes, use promo-banner.jpg

Bot:  Which contact list should I use?

User: contacts.xlsx

Bot:  📤 Broadcast Preview:
      
      Message: Olá {name}, aproveite 20% de desconto esta semana!
      Image: promo-banner.jpg
      Recipients: 127 VIP customers
      
      Send now or schedule?

User: Send now

Bot:  📤 Broadcasting...
      ✅ Broadcast complete! Sent to 127 contacts.
      
      View delivery report in Analytics.

Content Ideation

User: I need content ideas for our new product launch

Bot:  What product are you launching?

User: Wireless headphones

Bot:  What platform are you targeting?

User: Instagram

Bot:  Here are 5 content ideas for your wireless headphones launch:

      1. "Experience Sound Like Never Before 🎧"
         Key message: Premium audio quality
         CTA: Shop now, link in bio
         Hashtags: #WirelessFreedom #AudioExperience #NewLaunch
      
      2. "Cut the Cord, Not the Quality"
         Key message: Freedom without compromise
         CTA: Pre-order today
         Hashtags: #WirelessAudio #TechLife #MusicLovers
      
      3. "Your Music. Your Freedom."
         Key message: Lifestyle integration
         CTA: Discover more
         Hashtags: #OnTheGo #Wireless #Premium
      
      4. "30 Hours of Pure Sound"
         Key message: Battery life
         CTA: Learn more
         Hashtags: #AllDayBattery #WirelessHeadphones
      
      5. "Studio Sound, Everywhere"
         Key message: Professional quality
         CTA: Experience now
         Hashtags: #StudioQuality #Audiophile #TechGear
      
      Would you like me to generate images for any of these?

Image Generation

User: Generate an image for idea 1

Bot:  Generating marketing image...
      
      Prompt: "Premium wireless headphones floating in space with 
      sound waves emanating, modern minimalist style, product 
      photography, dark background with purple accent lighting"
      
      [Generated Image]
      
      ✅ Image generated! Would you like to:
      1. Post to Instagram
      2. Use in a broadcast
      3. Generate variations
      4. Download

User: Post to Instagram

Bot:  What caption should I use?

User: Experience Sound Like Never Before 🎧 #WirelessFreedom #NewLaunch

Bot:  ✅ Posted to Instagram!
      
      Post ID: 12345678
      Time: May 15, 2025 at 2:30 PM
      
      Track engagement in Analytics.

Audience Segmentation

Filter Examples

Building Segments

' Create reusable segments
WITH segment
    id = "SEG-" + FORMAT(GUID())
    name = "VIP São Paulo"
    filter = "Perfil=VIP AND cidade=São Paulo"
    count = COUNT(FIND "contacts.xlsx", filter)
    created_at = NOW()
END WITH

SAVE "segments.csv", segment

Configuration

Configure in marketing.gbot/config.csv:

Analytics & Reporting

Broadcast Analytics

' Get broadcast statistics
broadcast_id = "BROADCAST-20240115-1234"
logs = FIND "broadcast_log.csv", "broadcast_id = '" + broadcast_id + "'"

total_sent = COUNT(logs)
delivered = COUNT(FIND logs, "status = 'delivered'")
read = COUNT(FIND logs, "status = 'read'")
clicked = COUNT(FIND logs, "status = 'clicked'")

TALK "📊 Broadcast Report"
TALK "Total Sent: " + total_sent
TALK "Delivered: " + delivered + " (" + (delivered/total_sent*100) + "%)"
TALK "Read: " + read + " (" + (read/total_sent*100) + "%)"
TALK "Clicked: " + clicked + " (" + (clicked/total_sent*100) + "%)"

Customization

Adding Campaign Types

' campaign-email.bas
PARAM subject AS STRING DESCRIPTION "Email subject line"
PARAM body AS STRING DESCRIPTION "Email body content"
PARAM list_file AS FILE DESCRIPTION "Contact list"
PARAM filter AS STRING DESCRIPTION "Segment filter" OPTIONAL

DESCRIPTION "Send email marketing campaign"

IF filter THEN
    contacts = FIND list_file, filter
ELSE
    contacts = FIND list_file
END IF

FOR EACH contact IN contacts
    personalized_body = REPLACE(body, "{name}", contact.name)
    SEND MAIL contact.email, subject, personalized_body, []
    
    WITH log
        campaign_id = campaign_id
        contact_email = contact.email
        sent_at = NOW()
        status = "sent"
    END WITH
    
    SAVE "email_campaign_log.csv", log
NEXT

TALK "Email campaign sent to " + UBOUND(contacts) + " recipients."

Social Media Scheduling