If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/go-telegram-bot-api/telegram-bot-api shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live go-telegram-bot-api/telegram-bot-api repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/go-telegram-bot-api/telegram-bot-api.

What it runs against: a local clone of go-telegram-bot-api/telegram-bot-api — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in go-telegram-bot-api/telegram-bot-api | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 661 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of go-telegram-bot-api/telegram-bot-api. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/go-telegram-bot-api/telegram-bot-api.git
#   cd telegram-bot-api
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of go-telegram-bot-api/telegram-bot-api and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "go-telegram-bot-api/telegram-bot-api(\\.git)?\\b" \\
  && ok "origin remote is go-telegram-bot-api/telegram-bot-api" \\
  || miss "origin remote is not go-telegram-bot-api/telegram-bot-api (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 661 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~631d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/go-telegram-bot-api/telegram-bot-api"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

This is a pure Go wrapper library for the Telegram Bot API that provides lightweight bindings to interact with Telegram bots. It handles message sending/receiving, file uploads, webhook setup, and all core Telegram bot operations without adding abstraction layers or plugin systems—the goal is minimal wrapper code that maps directly to Telegram's HTTP API. Single-package monolithic library: bot.go contains the BotAPI client struct and core Send/Request methods; types.go defines all Telegram API struct types; configs.go and params.go build request configurations and parameters; helpers.go provides factory functions for common message types (NewMessage, NewPhotoUpload, etc.). Test files mirror the structure with _test.go suffixes.

Go developers building Telegram bots who need direct, low-level access to the Telegram Bot API without opinionated frameworks. This includes both polling-based bot developers (using GetUpdatesChan) and webhook-based deployments (e.g., on Google App Engine).

This is production-ready code: v5 is stable (shown in go.mod as version constraint), it has CI/CD via GitHub Actions (test.yml workflow), comprehensive test coverage (bot_test.go, types_test.go, params_test.go), and active documentation at go-telegram-bot-api.dev. The library is widely used in production bots and maintained at a sustainable pace.

Low risk overall: no external dependencies beyond Go stdlib (go.mod shows minimal deps), straightforward code directly mapping Telegram API, no breaking changes expected in v5 minor versions. The main risk is API-level changes from Telegram itself, which the maintainers must track. Single-author maintenance is a concern for very long-term sustainability, but the v5 API surface is stable.

No specific PR/milestone data visible in file list, but the library is in maintenance mode: documentation is well-established (docs/ folder with examples), test coverage is comprehensive, and the v5 API is stable. Activity likely focuses on tracking Telegram API updates and fixing edge cases rather than major feature work.

Clone and install: git clone https://github.com/go-telegram-bot-api/telegram-bot-api && cd telegram-bot-api && go mod download. No build step needed—this is an import library. To use in your project: go get github.com/go-telegram-bot-api/telegram-bot-api/v5.

Daily commands: This is a library, not an executable. To test locally: go test ./... runs the test suite (bot_test.go, types_test.go, params_test.go). To use in your own bot: create main.go, import the library, instantiate BotAPI with NewBotAPI(token), and call Send/GetUpdatesChan as shown in README examples.

• bot.go: Core BotAPI client struct and all high-level methods (Send, GetUpdatesChan, Request, ListenForWebhook) that developers call directly.
• types.go: Defines 100+ Go struct types (Message, User, Chat, Update, etc.) mapping Telegram API objects—the vocabulary of the entire library.
• configs.go: Message config types (MessageConfig, PhotoConfig, etc.) that implement the Chattable interface—where request payloads are built before sending.
• params.go: Low-level parameter builders (NewUpdate, InlineQueryResultArticle constructors) and the Fileable interface for file upload handling.
• helpers.go: Convenience factory functions (NewMessage, NewPhotoUpload, NewInlineKeyboardMarkup) that junior devs use to quickly construct API calls.
• bot_test.go: Integration tests showing real bot behavior—study this to understand the polling and webhook patterns in practice.
• docs/internals/adding-endpoints.md: The formal guide for extending the library with new Telegram API endpoints—required reading before contributing new methods.

Start in types.go to understand Telegram API struct mappings. For new methods: add a function to bot.go that builds a config in configs.go and calls bot.Request(). For new API types: add structs to types.go. For parameter builders: extend params.go. Always add tests following the _test.go pattern. Check docs/internals/adding-endpoints.md for the formal workflow.

Telegram token must be valid and passed to NewBotAPI(); invalid token panics in Debug mode. File uploads use multipart/form-data (see docs/internals/uploading-files.md)—use FileReader or FilePath configs, not raw bytes. GetUpdatesChan uses long polling with configurable timeout (Timeout field in UpdateConfig). Webhook mode requires HTTPS and a valid certificate (tests/cert.pem and tests/key.pem provided as examples). MessageID and ChatID are int64, not strings—type confusion is a common mistake. The library does minimal validation; Telegram API errors come back as non-200 HTTP responses.

• Long Polling (Updates Pattern) — GetUpdatesChan uses long polling with configurable timeout—critical for understanding the default update delivery model vs. webhooks.
• Multipart Form Data (File Uploads) — Telegram requires multipart/form-data for file uploads; this library abstracts it via Fileable interface and FileReader—you need to know this exists to upload files correctly.
• Interface-based Polymorphism (Chattable, Fileable) — The library uses Go interfaces to represent different request types (text message, photo, etc.) without inheritance—key to understanding how Send() handles any request type.
• Webhook Handlers (HTTPS + TLS Certificates) — Telegram webhooks require HTTPS and valid certificates; ListenForWebhook() and NewWebhookWithCert() handle setup—essential for Google App Engine deployments.
• JSON Unmarshaling with Embedded Structs — types.go uses Go struct embedding (e.g., Update embeds different *Message, *CallbackQuery) to represent Telegram's polymorphic responses—critical for parsing API JSON correctly.
• Token Bucket Rate Limiting (Implicit) — Telegram enforces strict rate limits; while this library doesn't implement backoff, understanding retry logic and rate limit headers is essential for production bots.

• telebot/telebot — Alternative Go Telegram bot library with higher-level abstractions (middleware, handlers) vs. go-telegram-bot-api's minimal approach—compare for feature gaps.
• tucnak/telebot — Another mature Go Telegram wrapper with different API design philosophy—useful reference for architectural decisions and missing features.
• python-telegram-bot/python-telegram-bot — Python equivalent library with richer examples and documentation; study it for missing features or API patterns to port to Go.
• go-telegram-bot-api/example_bots — Official companion repo with fully-runnable example bots (command handler, inline queries, etc.) demonstrating best practices for this library.
• tdlib/td — Lower-level Telegram TDLib C API—this Go library abstracts over the higher-level Telegram Bot API (different use case, but good to know the distinction).

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for params.go configuration structs

params.go contains numerous configuration struct types for API endpoints (MessageConfig, PhotoConfig, etc.) but params_test.go likely has minimal coverage. These structs are critical for correctness since they directly map to Telegram API parameters. Adding tests for marshaling, validation, and edge cases would catch bugs early and improve maintainability.

• [ ] Review current test coverage in params_test.go to identify gaps in struct validation tests
• [ ] Add tests for all config struct types ensuring required fields, field type conversions, and optional field handling
• [ ] Add tests for edge cases like empty strings, zero values, and boundary conditions for numeric fields
• [ ] Add tests for file parameter handling (referenced in docs/getting-started/files.md)
• [ ] Verify tests run with 'go test' and achieve >80% coverage on params.go

Add integration test workflow for Telegram Bot API endpoints

The test.yml workflow exists but likely only runs unit tests. Given this is an API client library, adding an optional integration test workflow (gated by secrets) would validate against live/sandbox Telegram API and catch breaking changes from Telegram's side. This would significantly improve confidence for releases.

• [ ] Create .github/workflows/integration-test.yml that runs on manual trigger or scheduled basis
• [ ] Add integration tests in tests/ directory (or new tests/integration/ subdirectory) that validate real API calls using test bot token stored as secret
• [ ] Test key endpoints: SendMessage, SendPhoto, GetUpdates, and file upload workflows referenced in bot.go
• [ ] Ensure integration tests skip gracefully if TELEGRAM_BOT_TOKEN secret is not available (for forks)
• [ ] Document in docs/getting-started/ or CONTRIBUTING.md how to run integration tests locally

Add missing documentation for Passport API types and usage

passport.go exists in the codebase but there is no corresponding documentation in docs/examples/ or docs/getting-started/. This is a complex feature that needs a dedicated guide. Adding a docs/examples/passport.md or docs/getting-started/passport-integration.md with real code examples would help users implement Telegram Passport functionality.

• [ ] Review passport.go to understand all exported types (PassportData, PassportFile, etc.)
• [ ] Create docs/examples/passport.md with a complete working example of receiving and validating passport data
• [ ] Document the setup requirements (certificates, fields, etc.) referenced in tests/cert.pem and tests/key.pem
• [ ] Add this new example to docs/SUMMARY.md under the examples section
• [ ] Cross-reference from docs/getting-started/README.md to the new passport guide

• Add missing test cases for passport.go (Passport API types are defined but have sparse test coverage compared to message types in types_test.go).
• Expand docs/examples/ with a fully-runnable inline-keyboard example showing callback query handling and InlineKeyboardMarkup—currently only skeleton docs exist.
• Create a helper function in helpers.go for building ReplyKeyboardMarkup with validation, since current helpers focus on InlineKeyboard and many bots need legacy keyboards.

The codebase is a wrapper library for the Telegram Bot API with minimal security concerns inherent to its design. The primary vulnerabilities are: (1) outdated Go runtime version (1.16) requiring immediate upgrade for security patches, (2) test certificates stored in version control, and (3) missing security disclosure policy. The library itself avoids common web vulnerabilities (SQLi, XSS) due to its nature as a Telegram API client wrapper. No evidence of hardcoded secrets or dangerous patterns detected. Recommended actions: upgrade Go version, establish security policy, and review dependency management practices.

• Medium · Outdated Go Version — go.mod. The project specifies go 1.16 in go.mod, which is significantly outdated. Go 1.16 was released in February 2021 and is no longer receiving security updates. This may expose the project to known vulnerabilities in the Go runtime and standard library. Fix: Update to a currently supported Go version (1.21 or later). Review the go.sum file and run 'go get -u' to update dependencies after upgrading Go.
• Medium · Test Certificates in Repository — tests/cert.pem, tests/key.pem. SSL/TLS certificates and keys (cert.pem, key.pem) are committed to the repository. While these appear to be test certificates, storing any cryptographic material in version control is a security anti-pattern and could establish bad practices. Fix: Move test certificates to a secure test data directory with appropriate .gitignore rules. Consider generating certificates dynamically during tests or using a dedicated test fixtures approach that doesn't commit sensitive material.
• Low · Missing Security Policy — Repository root. The repository does not appear to have a SECURITY.md or security policy document visible in the file structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file that outlines how users can report security vulnerabilities privately. Include contact information or a security advisory process.
• Low · No Dependency Pinning Information Visible — go.mod, go.sum. While go.sum exists, the go.mod file content is minimal. There's no visibility into whether indirect dependencies are properly vetted or if there's a lock strategy for production use. Fix: Regularly run 'go mod tidy' and 'go mod verify'. Use 'go list -m all' to audit all dependencies. Consider running 'go mod graph' to understand the dependency tree and identify unnecessary transitive dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.