fastbotty 0.0.4

Lightning-fast, super-simple Python bot framework for building powerful, interactive bots in under a minute using a single, clean YAML configuration file.

FastBotty

Lightning-fast, super-simple Python bot framework for building powerful, interactive bots in under a minute using a single, clean YAML configuration file.

FastBotty is a modern, webhook-driven bot framework built on FastAPI, designed for effortless creation of rich, interactive notification bots. Currently, it supports Telegram (via python-telegram-bot), with plans to expand to other platforms.

Receive HTTP webhooks from any source, transform payloads intelligently, and deliver beautifully formatted messages with full support for inline keyboards and media—all configured in one intuitive config.yml file.

Ideal for:

• Real-time alerts
• E-commerce order notifications
• Monitoring systems
• CI/CD pipeline updates
• Server health reporting
• Any integration requiring instant, engaging bot deliveries

---

✨ Features

• 🚀 Simple: Install, configure, and run in under 5 minutes.
• 🔌 Plugin System: Custom formatters without touching core code.
• 📱 All Chat Types: Private chats, groups, supergroups, and channels.
• 📢 Broadcast: Send to multiple chats simultaneously.
• 🖼️ Rich Media: Single images, photo galleries (up to 10), documents, videos, audio, and voice messages.
• 📍 Location Sharing: Send GPS coordinates with optional live tracking.
• 🎹 Inline Keyboards: Interactive buttons with dynamic templates.
• 💳 Payment Support: Send invoices with pay buttons for Telegram Stars and other providers.
• ⌨️ Reply Keyboards: Custom keyboards with buttons for contacts, locations, and more.
• 🤖 Command Handlers: Respond to /start, /help, etc.
• 🌐 Environment Variables: Universal ${VAR} support in all config fields.
• 🏷️ Custom Labels: Map order_id → 🆔 Order ID.
• 🔀 Field Mapping: Map nested JSON fields with dot notation.
• 📝 Jinja2 Templates: Conditionals, loops, and filters.
• 🎨 Formatters: Plain text, Markdown, or custom plugins.
• 🔒 Secure: API key authentication.
• 🌍 CORS Ready: Configurable CORS for web frontends.
• ♻️ Reliable: Automatic retries with exponential backoff.
• 🐳 Docker Ready: Easy containerized deployment.

---

🛠️ Quick Start

1. Install

pip install fastbotty

2. Create Project

fastbotty init my_notifier
cd my_notifier

3. Configure

Edit config.yaml:

bot:
  token: "${TELEGRAM_BOT_TOKEN}"
endpoints:
  - path: "/notify/orders"
    chat_id: "-1001234567890"
    formatter: "plain"

4. Run

export TELEGRAM_BOT_TOKEN="your-bot-token"
fastbotty run

5. Send Notification

curl -X POST http://localhost:8000/notify/orders \
  -H "Content-Type: application/json" \
  -d '{"message": "New order received!", "order_id": 123}'

---

📚 Documentation

• USAGE.md: Complete usage guide with examples.
• CONTRIBUTING.md: Guide for contributors.
• docs/PUBLISHING.md: Release and publishing guide.
• docs/FUTURE.md: Roadmap and planned features.

---

🔧 Configuration Reference

Bot Configuration

bot:
  token: "${TELEGRAM_BOT_TOKEN}" # Bot token (supports env vars)
  test_mode: false # Log instead of sending (for testing)
  webhook_url: "${WEBHOOK_URL}" # Public URL for receiving updates
  webhook_path: "/bot/webhook" # Webhook endpoint path

Templates

templates:
  order_received: |
    🛒 *New Order \#{{ order_id }}*

    Customer: {{ customer }}
    Total: {{ total }}

Endpoint Configuration

endpoints:
  - path: "/webhook/orders" # HTTP endpoint path
    chat_id: "8345389653" # Single chat ID
    chat_ids: # Or multiple chat IDs
      - "8345389653"
      - "-1001234567890"
      - "@my_channel"
    formatter: "markdown" # plain, markdown, or plugin name
    template: "order_received" # Use template instead of formatter
    parse_mode: "MarkdownV2" # Telegram parse mode
    labels: # Custom display labels
      order_id: "🆔 Order"
      customer: "👤 Customer"
    field_map: # Map incoming fields
      image_url: "product.photo" # Supports dot notation
      image_urls: "product.gallery"

Server Configuration

server:
  host: "0.0.0.0"
  port: 8000
  api_key: "${API_KEY}" # Optional authentication
  cors_origins: ["*"] # CORS allowed origins
logging:
  level: "INFO" # DEBUG, INFO, WARNING, ERROR

---

🌐 Environment Variables

All config fields support ${VAR} syntax with optional defaults:

bot:
  token: "${TELEGRAM_BOT_TOKEN}"
  webhook_url: "${WEBHOOK_URL}"
server:
  port: "${PORT:-8000}" # Use PORT or default to 8000
  cors_origins: ["${CORS_ORIGIN:-*}"]

Create a .env file:

TELEGRAM_BOT_TOKEN=your_bot_token
WEBHOOK_URL=https://yourapp.onrender.com
PORT=3000

Note: All CLI commands (run, validate, webhook) automatically load environment variables from a .env file in the current directory if it exists. You can use either exported environment variables or a .env file.

---

⚙️ CLI Commands

fastbotty init <name> # Create new project
fastbotty run # Start server
fastbotty run --reload # Start with auto-reload (dev)
fastbotty validate # Validate config file
fastbotty webhook setup # Register webhook with Telegram
fastbotty webhook info # Show webhook status
fastbotty webhook delete # Remove webhook
fastbotty --version # Show version

---

🔌 Custom Plugins

Create plugins/my_formatter.py:

from fastbotty import IPlugin

class MyFormatter(IPlugin):
    @property
    def name(self):
        return "my_formatter"

    def format(self, payload: dict, config: dict) -> str:
        prefix = config.get("prefix", "📢")
        return f"{prefix} {payload.get('message', '')}"

Use in config:

endpoints:
  - path: "/notify"
    chat_id: "123456789"
    formatter: "my_formatter"
    plugin_config:
      prefix: "🔔 Alert:"

---

📡 API Response

Success:

{
  "status": "sent",
  "message_id": 123,
  "chat_id": "8345389653"
}

Error (structured JSON):

{
  "detail": {
    "error": "invalid_api_key",
    "message": "Invalid or missing API key"
  }
}

Error codes: invalid_api_key, formatter_not_found, send_failed

---

🛠️ Development

Setup Development Environment

git clone https://github.com/venopyx/fastbotty.git
cd fastbotty
make install

Development Commands

source .venv/bin/activate
make test
make lint
make format
make build
make clean

Publishing

See docs/PUBLISHING.md for detailed release instructions.

Quick release:

make release version=1.0.4 notes=docs/RELEASE_NOTES.md

---

🔍 Getting Your Chat ID

1. Message @userinfobot on Telegram.
2. Or send a message to your bot and check:

   curl https://api.telegram.org/bot<TOKEN>/getUpdates
   

---

📜 License

MIT License – see LICENSE for details.