Skip to main content

Bots and Flows

Every Botgami project is one bot { } block that contains variables and flows. This page covers the top-level anatomy.

The bot block​

bot MyBot {
  // variables and flows go here
}

The name (MyBot) is an identifier. Inside the braces you declare variables and define flows. Everything your bot does lives here.

What a flow is​

A flow is a named block of logic bound to a trigger:

flow welcome on command "/start" {
  send.text("Hello!")
}
  • flow welcome — the flow's name (used in the graph and for your own reference).
  • on command "/start" — the trigger that runs it.
  • { ... } — the body: the steps that execute, top to bottom.

A bot can have as many flows as you like. Each handles one trigger. See Triggers for every kind.

The meta block (store listing)​

A meta { } block describes your bot for the Store: its title, description, category, and more. It's optional, but recommended for anything you publish.

bot MyBot {
  meta {
    name: "My Bot"
    slug: "my-bot"
    description: "A helpful assistant that does X, Y, and Z."
    author: "Your Name"
    version: "1.0.0"
    category: "productivity"
    tags: ["assistant", "demo"]
    icon: "🤖"
  }
}
KeyTypePurpose
nameStringDisplay title
slugStringURL-safe identifier
descriptionStringListing description
authorStringWho made it
versionStringSemantic version, e.g. "1.0.0"
categoryStringStore category
tagsArraySearch keywords
iconStringAn emoji or icon

package and comments​

A file may begin with a package declaration (commonly package main) — a namespace marker that's safe to keep at the top:

package main

bot MyBot { /* ... */ }

Comments use // for a line and /* ... */ for a block:

// This flow greets new users.
flow welcome on command "/start" {
  send.text("Hi!") /* inline note */
}

Imports (overview)​

To use a bundled library, add an import line before the bot block and call its subflows with dot notation:

import format from "format"

bot MyBot {
  flow price on command "/price" {
    let { result } = await format.money(amount: 9.5, symbol: "$")
    send.text(`That'll be ${result}`)
  }
}

See the Standard Library for everything you can import, and Subflows for writing your own reusable blocks.

A complete skeleton​

package main

import format from "format"

bot ExampleBot {
  meta {
    name: "Example"
    slug: "example"
    description: "A skeleton bot."
    icon: "✨"
  }

  // Variables
  global api_key: String = ""
  user visits: Number = 0
  shared total_users: Number = 0

  // A reusable subflow
  subflow greet(name: String) {
    send.text(`Welcome, ${name}!`)
    return {}
  }

  // Flows
  flow start on command "/start" {
    set { user.visits += 1 }
    await greet(name: user.first_name)
  }
}

Next​