botapi
A Telegram Bot API library for Go, implemented directly over MTProto using
gotd/td — not over HTTP to api.telegram.org.
It exposes the familiar Bot API surface
(types, methods, updates) but speaks MTProto on a persistent connection. That
sidesteps the Bot API server's rate limits, removes the getUpdates/webhook
round trip, and keeps the raw gotd/td client one method call away
(Bot.Raw()) for anything not yet covered.
Status: experimental. The library is hand-written and functional: it
connects and authorizes as a bot, serves updates over a persistent connection,
and exposes a broad typed Bot API surface — sending and editing, media,
keyboards, inline queries, payments and stars, gifts, stories, business
accounts, chat management, and the handler framework. A few areas remain
unimplemented over MTProto (see the guide); the raw
*tg.Client (Bot.Raw()) covers anything not yet typed. The API may still
change before a stable release.
Why MTProto instead of HTTP
|
HTTP Bot API client |
botapi |
| Transport |
HTTPS to api.telegram.org |
MTProto via gotd/td |
| Updates |
getUpdates long-poll / webhook |
persistent connection, no polling |
| Rate limits |
Bot API server limits |
MTProto limits only |
| Escape hatch |
none |
raw *tg.Client via Bot.Raw() |
Design goals
In priority order (see docs/architecture.md):
- Zero-reflection performance — fully typed request/response building, no
reflect in the hot path; allocation-tested like gotd/td.
- Type-safe unions & enums —
ChatID, InputFile, ChatMember,
ReplyMarkup, parse modes, etc. as sealed interfaces and typed constants,
not stringly-typed structs.
- First-class context & structured errors — context-first API; typed
errors (flood-wait, retry-after, network vs API vs not-implemented);
proactive rate limiting.
- A great handler framework — composable middleware, router and predicates
over a native MTProto update stream.
Usage
package main
import (
"context"
"github.com/gotd/botapi"
)
func main() {
// Bots still need an MTProto app identity (https://my.telegram.org).
// This is NOT the bot token.
bot, err := botapi.New("<bot-token>", botapi.Options{
AppID: 123456,
AppHash: "<app-hash>",
})
if err != nil {
panic(err)
}
bot.OnCommand("start", "Start the bot", func(c *botapi.Context) error {
_, err := c.Reply("Hello!")
return err
})
// Connects, authorizes as a bot, and serves updates until ctx is cancelled.
if err := bot.Run(context.Background()); err != nil {
panic(err)
}
}
See the guide for the full surface (sending, media,
keyboards, handlers, predicates, middleware, commands, files, chat management,
errors, pooling) and examples/ for runnable bots
(echo, buttons, inline, media, rich, background, advanced,
business).
Options.Storage is optional — leave it nil to keep session, peers and update
state in memory (nothing survives a restart). storage.Open("bot.bbolt")
persists all of it to a single bbolt file; close it on shutdown. Every example
under examples/ persists its session this way by default, so
they reconnect without re-authorizing.
Package layout
botapi (root) — the public library: the Bot client, options, and the
hand-written Bot API surface (types, methods, updates, handlers).
pool — runs and multiplexes many bots by token over one process.
storage — bbolt-backed session/peer/update-state storage.
internal/botdoc — fetches and extracts the published Bot API docs; kept as a
reference oracle and a conformance check against API-version drift.
cmd/botdoc — CLI to fetch and inspect the published Bot API docs.
Acknowledgements