YoBotz is a modular conversational automation system that gives businesses an intelligent interface for handling customer interactions through messaging platforms. It turns natural-language customer requests into structured actions — bookings, answers to common questions, and other business-specific workflows.
Design principles:
- Layered architecture — message transport, conversation orchestration, intent processing, business logic, and external integrations are separated, keeping the core independent of any single platform.
- Configurable foundation — adapts to different types of businesses with minimal changes.
- Extensible by design — additional messaging platforms, storage systems, AI services, and infrastructure such as Redis plug in without changing the core application.
- AI as a component — dedicated processing layers interpret requests and pass structured data into deterministic business logic, rather than treating the language model as the entire application.
YoBotz Lite is a lightweight, portfolio-focused version of the original YoBotz product and its larger production architecture. It is a simplified, local-focused implementation designed to showcase the project's architectural design, core concepts, and functionality. The repository intentionally omits certain production features, integrations, and infrastructure while preserving the fundamental architecture and design principles of the original system.
- Features
- Architecture
- Quick Start
- Configuration
- BusinessVault
- Admin API
- Project Structure
- Running Locally
- Contributing
- Documentation
| Category | Capabilities |
|---|---|
| Platforms | Telegram via the unified gateway; adapters are platform-agnostic |
| Multi-Business | Independent configurations, secrets, and response templates per business |
| Ordering | Cart management, categories, product catalog, variants, search [query], order confirmations, inquiry-mode orders |
| Booking | Time-slot reservations, natural language date parsing, availability checks |
| Inventory Sync | Pull products from Google Sheets; offline fallback to cached catalog |
| Notifications | Per-business Telegram bot alerts for orders, bookings, and system events |
| Session Persistence | Redis with automatic JSON fallback |
| Concurrency | Thread-safe session management for concurrent users |
| Onboarding | Multi-step customer registration wizard with LLM-powered response generation |
| Landing Page | Public chat widget and business setup wizard, embeddable on any website |
Note: YoBotz Lite includes a functional implementation of the landing page and onboarding flow, but these components are not considered finalized. They are included primarily to demonstrate the intended architecture and workflow and may differ from the more complete implementation used in the production system.
During business onboarding, an LLM can be used to generate initial response templates from provided business information, reducing the manual effort required to configure a new business. These generated templates become part of the business configuration and are then used by the chatbot during normal operation.
| Component | Responsibility |
|---|---|
unified_gateway/ |
FastAPI server, platform adapters, webhooks, message routing, delivery tracking, user mapping |
smart_engine/core/ |
Intent classification, session management, response templating, feature toggles |
smart_engine/features/ |
Ordering and booking workflow managers (incl. reservation time validation, sheet sync) |
notification_system/ |
Telegram alert delivery, daily summaries, log monitoring |
businesses/ |
Per-business YAML configs, product catalogs, response templates |
core/business_vault.py |
Per-business secrets (Redis or file-backed) |
core/business_registry.py |
Auto-discovery, hot-reload, admin management |
core/business_loader.py |
Config loading with ${VAR} expansion from the vault |
onboarding/ |
Customer registration wizard and business setup API |
- Python 3.10+
- Redis (optional; JSON fallback included)
- Telegram Bot Token
git clone <repository-url>
cd YoBotz_Lite
pip install -r requirements.txtpython3 -m uvicorn unified_gateway.server:app --host 0.0.0.0 --port 8000The server listens on http://localhost:8000.
For a public webhook URL with auto-configured Telegram webhooks, see Running Locally.
YoBotz Lite uses two .env files, one per scope. Both are gitignored — never commit real tokens.
One per business. Stores the secrets for that business only: its own bot, its notification bot, and its chat IDs. Read by BusinessVault (file mode).
# Telegram bot for this business
BOT_TOKEN=yo_bakery_bot_token
# Bot that sends alerts to the business owner
NOTIFICATION_BOT_TOKEN=yo_bakery_notification_token
# Who receives those alerts
BUSINESS_OWNER_CHAT_ID=987654321Note the key is
BOT_TOKENhere — notTELEGRAM_BOT_TOKEN. That distinction keeps business tokens separate from the system token below.
A single file at the project root. Holds system-level settings: which business is the default, Redis, logging, and the Telegram bots owned by the devs/team — not by any business. These are fallbacks when a business has no vault value.
# Which business handles unidentified chats
DEFAULT_BUSINESS=yo_bakery
# Dev/team bots (separate from business bots)
TELEGRAM_BOT_TOKEN=your_platform_bot_token
NOTIFICATION_BOT_TOKEN=your_team_notification_token
DEVELOPER_CHAT_ID=123456789
# Infra
REDIS_URL=redis://localhost:6379/0
# Server
TELEGRAM_SERVER_HOST=0.0.0.0
TELEGRAM_SERVER_PORT=8000
TELEGRAM_HOT_RELOAD=false
TELEGRAM_WEBHOOK_SECRET=
# Logging
LOG_LEVEL=INFO
LOG_FORMAT=text
DEBUG=false
# LLM keys (used by LLM-assisted onboarding)
HF_TOKEN=your_huggingface_token
GROQ_API_KEY=your_groq_api_key
# Apps Script (default for product endpoints; per-business override in vault)
APPS_SCRIPT_DEFAULT_TOKEN=In short: the root .env is for the system and the team; businesses/{name}/.env is for a single business. A business's own bots live in its own file — separate from the dev/team bots.
Each business in businesses/{name}/ has:
| File | Purpose |
|---|---|
business_config.yaml |
Feature toggles, business hours, AI model settings, reservation rules |
responses.yaml |
Parameterized response templates for all intents |
products.json |
Product catalog (ordering feature; may be generated by sheet sync) |
services.yaml |
Service definitions (booking feature) |
.env |
Per-business secrets (BusinessVault file mode) |
Example feature toggles in business_config.yaml:
features:
enable_ordering_system: true
enable_booking_system: true
enable_reservation_mode: trueMessages support two placeholder mechanisms, both resolved at runtime:
- Business-config placeholders —
{{hours}},{{address}},{{phone}},{{email}}are replaced frombusiness_config.yaml, so config changes propagate without regenerating responses. - Format variables —
{variable}style, populated by the engine (e.g.{day_display},{business_hours},{business_name}).
day_selected_prompt: |
Selected: {day_display}
Business hours: {{hours}}
Enter your preferred time (e.g., 14:00):YoBotz Lite uses BusinessVault for secure, isolated secrets management per business.
The mode is picked automatically: if REDIS_URL is set in the root .env, secrets live in Redis; otherwise the vault reads from the business's .env file.
| Mode | Backend | Use Case |
|---|---|---|
redis |
Redis server (when REDIS_URL is set) |
Production, shared infrastructure |
file |
businesses/{name}/.env (default) |
Development, single-machine |
In file mode you never touch code — just create businesses/{name}/.env (see Environment Variables) and the vault reads it automatically. Use the Python API only for programmatic access (Redis mode or custom keys):
from core.business_vault import BusinessVault
vault = BusinessVault("yo_bakery")
# Convenience accessors
token = vault.bot_token
notif_token = vault.notification_bot_token
chat_ids = vault.chat_ids
# Generic API
vault.get_secret("CUSTOM_KEY")
vault.set_secret("KEY", "value") # persists in Redis mode; in-memory only in file mode
vault.list_secrets()- Create a directory
businesses/{new_business}/withbusiness_config.yaml,responses.yaml, and any catalogs (or use the onboarding wizard to generate them). - Register secrets in the vault (file mode: a
.envin the business directory; redis mode:set_secret). - Restart the gateway — the
BusinessRegistryauto-discovers the new directory — or callPOST /admin/reload.
The gateway exposes admin endpoints for managing businesses, vault secrets, hot-reload, and product sync — full reference in the Gateway API Reference. No auth in the current build; protect behind a reverse proxy or VPN in production.
YoBotz_Lite/
├── auto_setup_gateway.py One-command ngrok + uvicorn launch
├── unified_gateway/ FastAPI server, adapters, webhooks, routing
│ ├── adapters/ Platform adapters (receive/send)
│ ├── server.py FastAPI application
│ ├── router.py Message routing + delivery tracking
│ ├── message_queue.py Optional Redis-backed processing
│ └── user_mapper.py Platform user ↔ internal identity mapping
├── smart_engine/ Business logic layer
│ ├── core/ Intent routing, sessions, responses, toggles
│ └── features/ Ordering and booking workflows
├── notification_system/ Telegram notifications, summaries, log monitor
├── core/ Cross-cutting infrastructure
│ ├── business_vault.py Per-business secrets
│ ├── business_registry.py Auto-discovery and hot-reload
│ └── business_loader.py Config loading with vault sync
├── onboarding/ Business setup + customer registration API
├── businesses/ Per-business configs and data
├── landing page/ Public chat widget and setup wizard
├── data/ Shared configs, sessions, logs, databases
├── requirements.txt Python dependencies
└── tools/ Standalone utilities
Quick setup with a public webhook URL (requires ngrok):
python3 auto_setup_gateway.pyThis starts an ngrok tunnel, boots the gateway, and auto-configures Telegram webhooks. Press Ctrl+C to stop everything cleanly.
Or run directly:
python3 -m uvicorn unified_gateway.server:app --host 0.0.0.0 --port 8000Set PUBLIC_URL to your public domain to auto-configure Telegram webhooks on startup. Without it, the server runs in local/dev mode.
Redis is recommended for production deployments. The system degrades gracefully to JSON file storage when Redis is unavailable.
Contributions are welcome. Read CONTRIBUTING.md first — it covers the code quality guidelines and the required PR body template.
PR body requirements — every pull request must include:
| Section | What to fill in |
|---|---|
| Summary | What the change does |
| Why | The problem it solves |
| Changes | Bullet list of main changes |
| Testing | How it was verified |
| Related Issues | Issue links or N/A |
| Checklist | Confirm code quality rules were followed |
The full template is in CONTRIBUTING.md → Pull Requests. PRs without a completed template will be sent back for updates.
- RESERVATION_CONFIG.md — Reservation and booking setup
- LOGGING_GUIDELINES.md — Logging standards
- CONTRIBUTING.md — Contribution guidelines
- unified_gateway/README.md — Gateway API reference