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.

In priority order (see docs/architecture.md):

1. Zero-reflection performance — fully typed request/response building, no reflect in the hot path; allocation-tested like gotd/td.
2. Type-safe unions & enums — ChatID, InputFile, ChatMember, ReplyMarkup, parse modes, etc. as sealed interfaces and typed constants, not stringly-typed structs.
3. First-class context & structured errors — context-first API; typed errors (flood-wait, retry-after, network vs API vs not-implemented); proactive rate limiting.
4. A great handler framework — composable middleware, router and predicates over a native MTProto update stream.

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.

• 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.

• Bot API reference — the spec.
• gotd/td — the MTProto engine.
• reference Bot API server.