README
¶
Install
togo install togo-framework/bot
togo install togo-framework/bot-telegram # or bot-discord / bot-slack
bot is togo's chat-bot subsystem. It defines a small Bot driver contract
plus a command / message handler registry so your app registers bot commands
once and they work across Telegram, Discord and Slack. Real platforms ship as
driver plugins; select one with the BOT_DRIVER env var.
| Platform | Plugin | Library |
|---|---|---|
| Telegram | bot-telegram |
go-telegram-bot-api |
| Discord | bot-discord |
discordgo |
| Slack | bot-slack |
slack-go (Socket Mode) |
Usage
Blank-import the base and a driver, then register handlers:
import (
"context"
_ "github.com/togo-framework/bot"
_ "github.com/togo-framework/bot-telegram"
"github.com/togo-framework/bot"
)
func init() {
// /weather <city>
bot.OnCommand("weather", func(ctx context.Context, b *bot.Service, m bot.Message) (string, error) {
if len(m.Args) == 0 {
return "usage: /weather <city>", nil
}
return "☀️ sunny in " + m.Args[0], nil
})
// Catch-all for non-command messages
bot.OnMessage(func(ctx context.Context, b *bot.Service, m bot.Message) (string, error) {
return "you said: " + m.Text, nil
})
}
Pick the platform at runtime:
BOT_DRIVER=telegram
TELEGRAM_BOT_TOKEN=123456:ABC...
A built-in /ping → pong 🏓 command is registered out of the box.
Sending proactively
From anywhere you have the kernel:
if svc, ok := bot.FromKernel(k); ok {
_ = svc.Send(ctx, channelID, "deploy finished ✅")
}
Contract
type Bot interface {
Start(ctx context.Context) error // receive loop (blocks)
Stop() error // shut down
Send(ctx context.Context, channel, msg string) error
}
type Handler func(ctx context.Context, b *Service, m Message) (string, error)
func RegisterDriver(name string, f DriverFactory) // drivers call this in init()
func OnCommand(name string, h Handler) // register "/name"
func OnMessage(h Handler) // register a catch-all
func FromKernel(k *togo.Kernel) (*Service, bool) // grab the runtime
Writing a new platform driver? Implement Bot, call bot.RegisterDriver in
init(), and invoke the dispatch func you're handed for every inbound message.
See bot-telegram for the canonical ~120-line example.
License
MIT © togo-framework
Documentation
¶
Overview ¶
Package bot is togo's chat-bot subsystem: a Bot driver contract plus a command/message handler registry so any plugin can add bot commands that work across platforms. Real platforms (Telegram, Discord, Slack) ship as driver plugins that call bot.RegisterDriver and depend on this package. Select one with BOT_DRIVER.
Install: `togo install togo-framework/bot` (blank-import registers it), then a driver, e.g. `togo install togo-framework/bot-telegram`.
import _ "github.com/togo-framework/bot"
import _ "github.com/togo-framework/bot-telegram"
bot.OnCommand("ping", func(ctx context.Context, b *bot.Service, m bot.Message) (string, error) {
return "pong 🏓", nil
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OnCommand ¶
OnCommand registers a handler for "/name". A leading slash is optional. The handler runs when a message starts with "/name". Later registrations for the same name win.
func OnMessage ¶
func OnMessage(h Handler)
OnMessage registers a handler invoked for every non-command message.
func ParseCommand ¶
ParseCommand splits "/cmd a b c" into ("cmd", ["a","b","c"], true). It returns ok=false when text is not a command.
func RegisterDriver ¶
func RegisterDriver(name string, f DriverFactory)
RegisterDriver registers a bot platform driver by name (call from a plugin's init()).
Types ¶
type Bot ¶
type Bot interface {
// Start begins receiving messages and blocks until ctx is canceled or Stop
// is called. Drivers invoke the dispatch func they were given for each message.
Start(ctx context.Context) error
// Stop shuts the bot down and releases resources.
Stop() error
// Send posts a message to a channel/chat.
Send(ctx context.Context, channel, msg string) error
}
Bot is implemented by platform driver plugins (telegram/discord/slack).
type DriverFactory ¶
DriverFactory builds a Bot from the kernel (env-configured). dispatch must be called by the driver for every inbound message; it routes to the registered command/message handlers and sends any reply.
type Handler ¶
Handler handles a command or message. Return a non-empty string to reply, or an error (the error is logged and no reply is sent).
type Message ¶
type Message struct {
Channel string // platform channel/chat ID — reply here
User string // sender's platform user ID
Username string // sender's display name / handle (best-effort)
Text string // raw message text
IsCommand bool // true when Text began with "/"
Command string // command name without the leading "/" (e.g. "ping")
Args []string // whitespace-split arguments after the command
Platform string // driver name: telegram | discord | slack
Raw map[string]any // platform-specific payload for advanced handlers
}
Message is an inbound chat message normalized across platforms.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the bot runtime stored on the kernel (k.Get("bot")).
func FromKernel ¶
FromKernel returns the bot Service if a driver was registered.
func (*Service) Dispatch ¶
Dispatch routes m to the matching command handler (if any) or to the message handlers, and sends back any non-empty reply. Drivers call this for each inbound message.
Source Files