Welcome to Botgami

Botgami is a developer-first, high-fidelity Telegram bot builder platform featuring a unified visual-code workspace. At its core, Botgami bots are authored in .botgami files—a clean, human-readable bot script format named BotGamiScript powered by Langium.

With Botgami, you write declarative BotGamiScript bot scripts in our integrated workspace, while a real-time, bi-directional visual editor projects your bot's logic as an interactive canvas graph. Visual gestures generate atomic script patches, and script changes compile instantly to update the graph preview.

---

The Botgami Workspace

Botgami blends code-based control with visual clarity:

• ✍️ Code Mode: Write declarative .botgami files with full in-browser IDE features: syntax highlighting, autocompletions (sourced directly from step contracts), hover tips, and type-checking diagnostics.
• 🎨 Graph Mode: Drag, rearrange, and inspect steps visually. Wires, ports, and layouts reflect the underlying DAG and sync automatically with your source code.
• ⚡ Execution Engine: Your BotGamiScript compiles via a rigorous 14-stage server-side pipeline (schema validation, type-checking, variable auto-declaration, and static mock simulations) before deploying.

---

A Taste of BotGamiScript

Here is a standard, complete .botgami blueprint showing the metadata, variables, triggers, interactive inputs, and inline layouts:

bot ShopBot {
  meta {
    name: "Shop Assistant"
    version: "1.0.0"
    category: "commerce"
    tags: ["shop", "checkout"]
    icon: "🛒"
  }

  // Declared, typed variables (synced to database)
  user points: Number = 100
  shared status_open: Boolean = true

  // Command trigger
  flow welcome on command "/start" {
    send.text(
      "Welcome to our 🛒 shop! Select an option:",
      reply_markup: {
        inline_keyboard: [
          [
            { text: "Browse Items 🏷", callback_data: "browse" },
            { text: "Check Points 💎", callback_data: "points" }
          ]
        ]
      }
    )
  }

  // Callback trigger
  flow on_points on callback "points" {
    // Backtick template interpolation
    send.text(`You currently have ${user.points} points! 💎`)
  }

  // Flow continuation and ask
  flow on_browse on callback "browse" {
    when shared.status_open {
      // Interactive continuation
      reply = ask.text(
        "What product category are you looking for?",
        timeout: 60,
        on_timeout: {
          send.text("Session timed out.")
        }
      )

      send.text(`Searching for products in category: ${reply}... ⏳`)
    } else {
      send.text("Sorry, the store is closed right now!")
    }
  }
}

---

Core Concepts

As you build with Botgami, you will work with three central pillars:

1. Flows & Subflows

• Flows: The top-level triggers that react to Telegram commands, text messages, inline buttons, or schedules.
• Subflows: Reusable function blocks (subflow my_func() -> { outputs } { ... }) that accept typed arguments, suspend execution for user answers, and return typed values back to the calling flow via await.

2. Variable Scopes

Botgami supports four main scopes, each mapped to high-speed persistent storage:

Scope	Persistence	Declared in Script	Purpose
user.*	Persistent	Yes	Custom user profile data (e.g. user.points). Coexists with automatic Telegram read-only built-ins (e.g. user.first_name).
shared.*	Persistent	Yes	Bot-wide variables shared by all users (e.g. shared.status_open).
global.*	Read-only	Yes	Static, deploy-time parameters (e.g. global.admin_id).
flow.*	Ephemeral	No (Auto-inferred)	Temporary variables active only during a single flow run.

3. Template Literals & Expressions

• Template Literals: Enclosed in backticks with ${var} placeholders for seamless text blending.
• Bare Expressions: Standard mathematical, string, or boolean expressions evaluated in a sandboxed runtime. No wrappers or opaque text strings—everything type-checks directly in the IDE.

---

Ready to Start?

Whether you're building a simple feedback bot or a multi-branching booking engine, start with our step-by-step guides:

• 🚀 Quick Start Guide — Write your first flow in under 5 minutes.
• 📚 Core Concepts — Learn about the compiled DAG execution and continuation runtime.
• 🧩 Statement Reference — The complete reference manual for every trigger, action, and expression statement.
• ⚡ Advanced Topics — Deep dive into scopes, CEL evaluators, custom keyboards, and reusable subflows.