# Telegram — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-19 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [what-is-the-telegram-platform](concepts/what-is-the-telegram-platform.md) | telegram, bot-api, client-api | high | 2026-06-19 | | [creating-a-bot-with-botfather](concepts/creating-a-bot-with-botfather.md) | botfather, token, setup | high | 2026-06-19 | | [bot-features](concepts/bot-features.md) | commands, menu, privacy | high | 2026-06-19 | | [receiving-updates](concepts/receiving-updates.md) | updates, webhooks, polling | high | 2026-06-19 | | [keyboards-and-interface](concepts/keyboards-and-interface.md) | keyboards, inline, callback | high | 2026-06-19 | | [inline-mode](concepts/inline-mode.md) | inline, inline-query | high | 2026-06-19 | | [mini-apps](concepts/mini-apps.md) | mini-apps, web-apps, initdata | high | 2026-06-19 | | [payments-and-stars](concepts/payments-and-stars.md) | payments, stars, invoices | high | 2026-06-19 | | [games](concepts/games.md) | games, html5 | high | 2026-06-19 | | [messages-and-formatting](concepts/messages-and-formatting.md) | messages, formatting, media | high | 2026-06-19 | | [client-api-and-tdlib](concepts/client-api-and-tdlib.md) | mtproto, tdlib, client-api | high | 2026-06-19 | ## Entities | Page | Tags | Updated | |------|------|---------| | [bot-api](entities/bot-api.md) | bot-api, http, endpoint | 2026-06-19 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [bot-api-method-catalog](summaries/bot-api-method-catalog.md) | Bot API reference | methods & types map | 2026-06-19 | | [chat-and-user-ids](summaries/chat-and-user-ids.md) | id conventions | chat/user/channel ids | 2026-06-19 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [building-your-first-bot](syntheses/building-your-first-bot.md) | end-to-end bot build | 2026-06-19 | | [bot-faq-casebook](syntheses/bot-faq-casebook.md) | FAQ + webhook + features gotchas | 2026-06-19 | ## Statistics - **Total pages**: 16 - **Concepts**: 11 - **Entities**: 1 - **Summaries**: 2 - **Syntheses**: 2 - **Sources ingested**: 14 core.telegram.org developer pages (bots, features, Bot API reference, Mini Apps, payments, inline, webhooks, tutorial, FAQ, games, client API, MTProto, TDLib, ids) - **High confidence**: 15 - **Medium confidence**: 1 --- title: "Bot Features" type: concept tags: [features, commands, menu, privacy, groups] updated: 2026-06-19 confidence: high sources: [raw/web_community-telegram-bot-features.md] --- # Bot Features Beyond sending messages, the Bot API offers tools for building rich, flexible interfaces. ## Commands **Commands** are `/`-prefixed words highlighted in the chat that users tap to send instantly. Register them with BotFather (`/setcommands`) or `setMyCommands`; they appear in a menu next to the input field. Scope commands per chat type, language, or user with command scopes. Common convention: `/start` (entry point, can carry a deep-link parameter), `/help`, `/settings`. ## The menu button & deep linking - **Menu button** — a customizable button by the input field that opens commands or launches a [Mini App](mini-apps.md). - **Deep links** — `https://t.me/?start=` opens the bot and sends `/start `, enabling referral/onboarding flows. ## Groups & privacy - Bots can be added to **groups** and **channels** (as admins for moderation). - **Privacy mode** (default on) means a group bot only receives messages that are commands, replies to it, or mentions — not every message. Disable via BotFather to see all messages (e.g. for moderation bots). - **Admin rights** gate moderation actions (ban, delete, pin). ## Interface elements Reply keyboards, inline keyboards, the input-field menu, and more — covered in [keyboards-and-interface](keyboards-and-interface.md). Bots can also set a profile, description, and "about" text via BotFather. Rich content (formatting, media) is in [messages-and-formatting](messages-and-formatting.md). --- title: "Client API (MTProto) & TDLib" type: concept tags: [mtproto, client-api, tdlib, userbot] updated: 2026-06-19 confidence: high sources: [raw/web_community-telegram-apis.md, raw/web_community-mtproto-mobile-protocol.md, raw/web_community-telegram-database-library.md] --- # Client API (MTProto) & TDLib Beyond the [Bot API](../entities/bot-api.md), Telegram offers a lower-level **client API** for building full Telegram clients and user-account automation. ## The Telegram API & MTProto The **Telegram API** lets you build customized clients that log in as a **user** (with a phone number), accessing the complete feature set the official apps use — not just the bot subset. It communicates over **MTProto**, Telegram's custom encryption/transport protocol designed for speed and security on mobile networks (handling authorization, encryption, and serialization of API calls defined by the TL schema). To use it you need an **`api_id`/`api_hash`** (obtained from my.telegram.org), then authenticate a user session. This is far more involved than the Bot API and is governed by stricter usage rules. ## TDLib (Telegram Database Library) **TDLib** is the official cross-platform library that wraps MTProto and the Telegram API into a high-level, consistent interface. It handles the hard parts — encryption, network, **local database and caching, synchronization** across devices, and updates — so you can build a client in many languages (C++, with bindings for Java, C#, Python, etc.) without implementing MTProto yourself. The official apps and many third-party clients are built on it. ## Bot API vs Client API | | Bot API | Client API / TDLib | |---|---|---| | Identity | bot account (token) | user account (phone) | | Transport | HTTPS/JSON | MTProto | | Scope | bot feature subset | full Telegram feature set | | Complexity | low | high | | Typical use | bots, automation in chats | custom clients, userbots | Most developers want the [Bot API](../entities/bot-api.md). Reach for MTProto/TDLib only when you need user-level capabilities the Bot API can't provide. --- title: "Creating a Bot with BotFather" type: concept tags: [botfather, token, setup, getting-started] updated: 2026-06-19 confidence: high sources: [raw/web_community-from-botfather-to-hello-world.md, raw/web_community-bots-an-introduction-for-developers.md] --- # Creating a Bot with BotFather **BotFather** is the bot that creates and manages all other bots — the entry point to bot development. ## Creating a bot 1. Open a chat with **@BotFather**. 2. Send `/newbot`, choose a **name** and a **username** (must end in `bot`, e.g. `my_test_bot`). 3. BotFather returns an **authorization token** like `123456:ABC-DEF...` — your bot's secret credential. ## The token The token authenticates every Bot API request. Requests go to: ``` https://api.telegram.org/bot/ ``` e.g. `https://api.telegram.org/bot/getMe`. **Keep the token secret** — anyone with it controls your bot; regenerate it via BotFather if leaked. ## Configuring the bot (BotFather commands) - `/setdescription`, `/setabouttext`, `/setuserpic` — profile. - `/setcommands` — the command menu users see ([bot-features](bot-features.md)). - `/setjoingroups`, `/setprivacy` — group behavior and privacy mode (whether the bot sees all group messages or only commands). - `/setinline` — enable [inline mode](inline-mode.md); `/setdomain` for login; `/newapp` for [Mini Apps](mini-apps.md); `/mybots` to manage everything. ## Hello world Any HTTPS-capable tool works. Send a message: ``` https://api.telegram.org/bot/sendMessage?chat_id=&text=Hello ``` Then move to [receiving updates](receiving-updates.md) so the bot can react. End-to-end walkthrough: [building-your-first-bot](../syntheses/building-your-first-bot.md). --- title: "Games" type: concept tags: [games, gaming-platform, html5] updated: 2026-06-19 confidence: high sources: [raw/web_community-gaming-platform.md] --- # Games The **Telegram Gaming Platform** lets bots serve **HTML5 games** that run inside Telegram, with built-in high-score tables shared in the chat where the game is played. ## How it works 1. Register a game with **BotFather** (`/newgame`), giving it a short name, title, and description. 2. Send the game with **`sendGame`** (or as an [inline](inline-mode.md) result), which posts a message with a **Play** button. 3. Tapping Play opens your **HTML5 game URL** (you host the game) in Telegram's in-app browser, passing context so the game can identify the user and chat. 4. Report scores with **`setGameScore`**; fetch leaderboards with **`getGameHighScores`**. Telegram shows high scores right in the chat and notifies when records are beaten. ## Notes - You host and build the actual game (any web tech); Telegram provides distribution, identity, and the social high-score layer. - Games are a precursor to / overlap with [Mini Apps](mini-apps.md), which are the more general framework for rich in-Telegram web experiences (and support [payments/Stars](payments-and-stars.md) for monetization). For a pure arcade-style game with native leaderboards, the Gaming Platform is the purpose-built path; for full apps/stores, use Mini Apps. --- title: "Inline Mode" type: concept tags: [inline, inline-query, inline-results] updated: 2026-06-19 confidence: high sources: [raw/web_community-inline-bots.md, raw/web_community-telegram-bot-features.md] --- # Inline Mode **Inline mode** lets users call your bot from **any chat** by typing `@yourbot ` in the input field — without adding the bot to that chat or sending it a message. The bot returns results the user can pick and send inline. ## How it works 1. Enable inline via BotFather (`/setinline`, with a placeholder prompt). 2. When a user types `@yourbot something`, Telegram sends your bot an **`inline_query`** update with the query text and user. 3. Your bot replies with **`answerInlineQuery`** — an array of **results** (articles, photos, GIFs, videos, documents, etc.), each with content and optional [inline keyboard](keyboards-and-interface.md). 4. The user taps a result; it's sent into the chat. You can receive a `chosen_inline_result` update to know what was picked (enable feedback via BotFather). ## Use cases Content lookups usable everywhere: GIF/sticker search, translations, polls, file search, "share from my service" — the classic example is `@gif` and `@vid`. Because it works in any chat, group, or channel, inline mode is how a bot reaches users without being a chat participant. ## Tips - **Cache** results (`cache_time`) for repeated queries. - Use `switch_pm_text`/`switch_pm_parameter` to send users to a private chat for setup (e.g. authentication) when needed. - Results can themselves carry [callback buttons](keyboards-and-interface.md) for further interaction. --- title: "Keyboards & Interface" type: concept tags: [keyboards, inline-keyboard, reply-keyboard, callback] updated: 2026-06-19 confidence: high sources: [raw/web_community-telegram-bot-features.md, raw/web_community-telegram-bot-api.md] --- # Keyboards & Interface Bots build interactive UI primarily through two kinds of keyboards attached to messages. ## Reply keyboards (`ReplyKeyboardMarkup`) Replace the user's normal keyboard with a grid of **buttons that send predefined text** (or share contact/location, or open a [Mini App](mini-apps.md)). Tapping a button sends that text as a message from the user. Good for menus and guided flows. `ReplyKeyboardRemove` hides it; `one_time_keyboard` hides it after one use; `selective` targets specific users. ## Inline keyboards (`InlineKeyboardMarkup`) Buttons attached **to a specific message** that don't send text. Button types: - **`callback_data`** — sends a `callback_query` update to your bot (tapping triggers backend logic without a new message); answer with `answerCallbackQuery` (optionally a toast/alert). - **`url`** — opens a link. - **`web_app`** — launches a [Mini App](mini-apps.md). - **`switch_inline_query`** — starts an [inline](inline-mode.md) query. - **`pay`** — a payment button ([payments](payments-and-stars.md)). - **`login_url`** — Telegram Login. Inline keyboards are the backbone of interactive bots: menus that edit the same message in place (`editMessageText`/`editMessageReplyMarkup`) create app-like navigation without chat clutter. ## Other interface bits - **Force reply** (`ForceReply`) — prompt the user to reply to a specific message. - **Menu button** and **commands** ([bot-features](bot-features.md)). - Typing/upload **chat actions** (`sendChatAction`) for "bot is typing…" feedback. Choosing: reply keyboards for simple text menus; inline keyboards for anything that needs callbacks, in-place editing, or app launches. --- title: "Messages, Media & Formatting" type: concept tags: [messages, formatting, markdown, html, media] updated: 2026-06-19 confidence: high sources: [raw/web_community-telegram-bot-api.md, raw/web_community-telegram-bot-features.md] --- # Messages, Media & Formatting ## Sending content The Bot API has a `send*` method per content type: `sendMessage`, `sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, `sendVoice`, `sendAnimation`, `sendSticker`, `sendLocation`, `sendVenue`, `sendContact`, `sendPoll`, `sendDice`, and `sendMediaGroup` (albums). Files are sent by uploading (multipart), by URL, or by reusing a **`file_id`** from a previously sent file (the cheapest — no re-upload). ## Text formatting Style text with `parse_mode`: - **`MarkdownV2`** — `*bold*`, `_italic_`, `__underline__`, `~strikethrough~`, `||spoiler||`, `` `code` ``, ```` ```pre``` ````, `[text](url)`. Note MarkdownV2 requires escaping many special characters. - **`HTML`** — ``, ``, ``, ``, ``, ``, `
`, ``, `
`. Generally easier to generate safely than MarkdownV2.
- Or pass explicit **`entities`** (offset/length/type) instead of a parse mode.

## Editing & managing

- **Edit** sent messages: `editMessageText`, `editMessageCaption`, `editMessageReplyMarkup`, `editMessageMedia` — the basis of in-place [inline-keyboard](keyboards-and-interface.md) UIs.
- **Delete**: `deleteMessage` (within allowed time).
- **Reply / quote / forward / pin**, reactions (`setMessageReaction`), and `copyMessage`.

## Limits to respect

Message length caps (~4096 chars text), rate limits (avoid flooding a chat; broadcasting has its own limits), and file size limits for upload vs download. The complete method/type list is the [bot-api-method-catalog](../summaries/bot-api-method-catalog.md).





---
title: "Mini Apps (Web Apps)"
type: concept
tags: [mini-apps, web-apps, webapp, frontend]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-telegram-mini-apps.md, raw/web_community-telegram-bot-features.md]
---

# Mini Apps (Web Apps)

**Mini Apps** are web applications (HTML/JS/CSS) that launch **inside Telegram** — full custom UIs that can completely replace a bot's chat-based interface. They power stores, games, tools, and full products living within the app.

## Launching a Mini App

A Mini App is opened from:

- A **menu button** ([bot-features](bot-features.md)) or a **keyboard `web_app` button** ([keyboards-and-interface](keyboards-and-interface.md)).
- An **inline button**, a **direct link** (`t.me//`), or the **attachment menu**.

Telegram loads your URL in an in-app browser and injects the **`window.Telegram.WebApp`** JavaScript object.

## The WebApp JS bridge

`Telegram.WebApp` gives the Mini App native-feeling integration:

- **Theme** — match Telegram's colors (`themeParams`, light/dark).
- **UI controls** — `MainButton`, `BackButton`, `SettingsButton`, haptic feedback, popups, scanning QR.
- **Viewport** — expand/size, safe areas.
- **Cloud storage & device storage** — persistent per-user storage; secure storage for sensitive data.
- **`initData`** — signed launch data identifying the user.

## Authentication (critical)

The Mini App receives **`initData`** containing the user and an HMAC **hash**. Your backend **must validate** that hash using your bot token before trusting the user identity — otherwise anyone can forge `initData`. This is the single most important security step for Mini Apps.

## Sending data back

`Telegram.WebApp.sendData()` returns data to the bot (for keyboard-button apps), or the Mini App calls your own backend directly. Payments inside Mini Apps use the [payments](payments-and-stars.md) flow (including Telegram Stars for digital goods).





---
title: "Payments & Telegram Stars"
type: concept
tags: [payments, stars, invoices, checkout]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-bot-payments-api.md]
---

# Payments & Telegram Stars

The **Bot Payments API** lets bots accept payment for goods and services. Telegram itself doesn't process or collect payment info — it's a free, open platform that routes between buyers and sellers.

## Two payment tracks

- **Physical goods & services** — paid via third-party **payment providers** (Stripe, etc.) connected through BotFather. Real-world currency; the provider handles money + KYC.
- **Digital goods & services** — paid with **Telegram Stars**, Telegram's in-app currency. Required for digital/virtual items per platform rules; Stars are purchased by users in-app and can be paid out by developers.

## The flow

1. **`sendInvoice`** (or an invoice in a [Mini App](mini-apps.md)) presents the product, price, and a **Pay** button.
2. The user fills in payment details (for physical goods) or confirms Stars.
3. Your bot receives a **`pre_checkout_query`** update — you must answer with **`answerPreCheckoutQuery`** within ~10 seconds (approve or reject, e.g. if out of stock).
4. On success, a **`successful_payment`** message arrives confirming the order.

## Key points

- **Provider token** (for physical goods) comes from BotFather → Payments; **Stars** need no provider.
- Always validate the order in `pre_checkout_query` before approving.
- Support **shipping queries** for physical goods that need addresses/shipping options.
- Refunds for Stars are supported via the API.

Payments work in chats, [inline](inline-mode.md) results, and [Mini Apps](mini-apps.md). Use Stars for anything digital; providers for physical.





---
title: "Receiving Updates: Webhooks vs Long Polling"
type: concept
tags: [updates, webhooks, getupdates, polling]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-marvin-s-marvellous-guide-to-all-things-webhook.md, raw/web_community-telegram-bot-api.md]
---

# Receiving Updates: Webhooks vs Long Polling

A bot reacts to **Updates** — JSON objects describing new messages, callback queries, inline queries, etc. There are two ways to receive them; you pick one (they're mutually exclusive).

## Long polling — `getUpdates`

Your bot repeatedly calls **`getUpdates`**; Telegram holds the request open and returns updates as they arrive. Simple to start: no public server, no TLS, works behind NAT/локально. You track an `offset` (the last update id + 1) to mark updates as processed. Good for development and low-to-moderate traffic.

## Webhooks — `setWebhook`

You give Telegram a **public HTTPS URL** via `setWebhook`; Telegram **pushes** each update to it as a POST as soon as it happens. Advantages: instant delivery, no polling loop, fewer wasted CPU cycles, better response time at scale.

Requirements (the common gotchas):

- A **valid HTTPS** endpoint — supported ports are **443, 80, 88, 8443**; a publicly-reachable URL with a valid certificate (or upload a self-signed cert).
- Respond quickly (2xx); do slow work asynchronously or Telegram retries.
- Secure it: use a hard-to-guess URL path and/or the `secret_token` (Telegram sends `X-Telegram-Bot-Api-Secret-Token`) so only Telegram can post to you.

## The Update object

Each update carries exactly one of: `message`, `edited_message`, `callback_query` (inline-button taps), `inline_query` ([inline mode](inline-mode.md)), `pre_checkout_query` ([payments](payments-and-stars.md)), `my_chat_member`, etc. Configure which types you receive with `allowed_updates`. Switching between polling and webhook requires deleting the other (`deleteWebhook`). The full update/type list is in the [bot-api-method-catalog](../summaries/bot-api-method-catalog.md).





---
title: "The Telegram Developer Platform"
type: concept
tags: [telegram, platform, bot-api, client-api, overview]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-bots-an-introduction-for-developers.md, raw/web_community-telegram-apis.md]
---

# The Telegram Developer Platform

Telegram exposes **two distinct APIs**, free of charge, plus libraries on top:

## Bot API

The **Bot API** is an HTTP interface for building **bots** — special accounts that run software instead of a person, with **no extra phone number** required. You talk to bots through normal Telegram chats; behind the scenes a bot is a program that queries the Bot API. This is the surface most developers use, and the focus of this wiki:

- Simple HTTPS requests/JSON; no need to understand Telegram's low-level protocol.
- Bots can send messages, files, locations, stickers; build [keyboards and interfaces](keyboards-and-interface.md); run [inline](inline-mode.md); host [Mini Apps](mini-apps.md); take [payments](payments-and-stars.md).
- Created and configured through **BotFather** ([creating-a-bot-with-botfather](creating-a-bot-with-botfather.md)).

## Client API (MTProto)

The **Telegram API / MTProto** lets you build full **Telegram clients** (like the official apps) — log in as a *user* (not a bot), access the full feature set, and implement custom clients. It speaks the [MTProto protocol](client-api-and-tdlib.md) and is far lower-level than the Bot API. **TDLib** wraps it into a cross-platform library.

## Which to use

- Automate/serve users in chats, stores, tools → **Bot API** ([bot-api](../entities/bot-api.md)).
- Build a custom user-facing Telegram client or userbot → **Client API / TDLib** ([client-api-and-tdlib](client-api-and-tdlib.md)).

There's also a **Gateway API** for sending verification codes via Telegram instead of SMS. Method/type map: [bot-api-method-catalog](../summaries/bot-api-method-catalog.md). Most of this wiki covers the Bot API.





---
title: "The Bot API"
type: entity
tags: [bot-api, http, endpoint, reference]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-telegram-bot-api.md]
---

# The Bot API

The **Bot API** is the HTTP interface for Telegram bots — the primary developer surface ([what-is-the-telegram-platform](../concepts/what-is-the-telegram-platform.md)).

## Endpoint shape

```
https://api.telegram.org/bot/
```

- **Methods** are called via GET or POST; parameters as query string, `application/x-www-form-urlencoded`, or JSON; file uploads as `multipart/form-data`.
- Every response is JSON: `{ "ok": true, "result": ... }` on success, or `{ "ok": false, "error_code": N, "description": "..." }` on failure (often with `parameters.retry_after` for rate limits).
- **File downloads**: `getFile` returns a `file_path`, then fetch `https://api.telegram.org/file/bot/`.

## Structure of the reference

The Bot API docs (one ~500KB page, mirrored whole in `raw/`) are organized as:

- **Getting updates** — `getUpdates`, `setWebhook`, the `Update` type ([receiving-updates](../concepts/receiving-updates.md)).
- **Available types** — `User`, `Chat`, `Message`, `MessageEntity`, keyboards, etc.
- **Available methods** — `sendMessage` and the full `send*`/`edit*`/`delete*` family ([messages-and-formatting](../concepts/messages-and-formatting.md)).
- **Updating messages**, **Stickers**, **Inline mode** ([inline-mode](../concepts/inline-mode.md)), **Payments** ([payments-and-stars](../concepts/payments-and-stars.md)), **Games** ([games](../concepts/games.md)), **Mini Apps** ([mini-apps](../concepts/mini-apps.md)).

## Self-hosting

The Bot API server is open source; you can run your **own Bot API server** for higher limits (larger file uploads/downloads, local mode) instead of `api.telegram.org`. The method-by-method map is in [bot-api-method-catalog](../summaries/bot-api-method-catalog.md).

## Versioning

The API is versioned by dated releases (Bot API X.Y); new features (Stars, reactions, Mini App capabilities) ship continuously — check the changelog for the minimum version a feature requires.





---
title: "Activity Log"
type: log
---

# Activity Log

Append-only record of all wiki changes.

## Format

Each entry follows this format:
```
### YYYY-MM-DD HH:MM — [Action Type]
- **Source/Trigger**: what initiated the action
- **Pages created**: list of new pages
- **Pages updated**: list of updated pages
- **Notes**: any contradictions flagged, decisions made
```

---

### 2026-04-08 00:00 — Setup

- **Source/Trigger**: Repository initialized
- **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md
- **Pages updated**: none
- **Notes**: Empty knowledge base ready for first source ingestion

### 2026-06-19 00:00 — Initial curation (medium rung)

- **Source/Trigger**: 14 core.telegram.org developer pages (web_urls)
- **Pages created**: 11 concepts, 1 entity (bot-api), 2 summaries (bot-api-method-catalog, chat-and-user-ids), 2 syntheses (building-your-first-bot, bot-faq-casebook)
- **Pages updated**: index.md
- **Notes**: No llms.txt (the path 404s). Bot API reference is a ~500KB single page — catalogued not reproduced. Bot developer surface is the focus; client API (MTProto/TDLib) summarized. bot-faq-casebook confidence:medium.





---
title: "Bot API Method & Type Catalog"
type: summary
tags: [catalog, methods, types, reference]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-telegram-bot-api.md]
---

# Bot API Method & Type Catalog

Map of the Bot API surface (full reference mirrored in `raw/web_community-telegram-bot-api.md`, ~500KB). Use this to find the method/type, then read the raw page for exact parameters.

## Getting updates
`getUpdates`, `setWebhook`, `deleteWebhook`, `getWebhookInfo`; types `Update`, `WebhookInfo`. → [receiving-updates](../concepts/receiving-updates.md)

## Core types
`User`, `Chat`, `ChatFullInfo`, `Message`, `MessageEntity`, `MessageId`, `ReactionType`, `LinkPreviewOptions`.

## Sending messages
`sendMessage`, `sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, `sendVoice`, `sendAnimation`, `sendSticker`, `sendLocation`, `sendVenue`, `sendContact`, `sendPoll`, `sendDice`, `sendMediaGroup`, `sendChatAction`, `forwardMessage(s)`, `copyMessage(s)`. → [messages-and-formatting](../concepts/messages-and-formatting.md)

## Updating & managing
`editMessageText/Caption/Media/ReplyMarkup`, `deleteMessage(s)`, `pinChatMessage`, `setMessageReaction`.

## Keyboards & queries
Types `ReplyKeyboardMarkup`, `InlineKeyboardMarkup`, `ReplyKeyboardRemove`, `ForceReply`; `answerCallbackQuery`. → [keyboards-and-interface](../concepts/keyboards-and-interface.md)

## Chat & member management
`getChat`, `getChatMember`, `banChatMember`, `restrictChatMember`, `promoteChatMember`, `setChatPermissions`, `createChatInviteLink`, admin/title/photo setters.

## Bot config
`getMe`, `setMyCommands`/`getMyCommands`/`deleteMyCommands`, `setMyName/Description/ShortDescription`, `setChatMenuButton`, `setMyDefaultAdministratorRights`.

## Files
`getFile` (+ file download URL), reusing `file_id`.

## Specialized surfaces
- **Stickers** — `sendSticker`, `getStickerSet`, `createNewStickerSet`, `addStickerToSet`.
- **Inline** — `answerInlineQuery`, `answerWebAppQuery`; types `InlineQuery`, `InlineQueryResult*`. → [inline-mode](../concepts/inline-mode.md)
- **Payments** — `sendInvoice`, `createInvoiceLink`, `answerShippingQuery`, `answerPreCheckoutQuery`, `refundStarPayment`. → [payments-and-stars](../concepts/payments-and-stars.md)
- **Games** — `sendGame`, `setGameScore`, `getGameHighScores`. → [games](../concepts/games.md)
- **Mini Apps** — `answerWebAppQuery`, `setChatMenuButton`. → [mini-apps](../concepts/mini-apps.md)

For exact parameters, required vs optional, and return types, read the specific section of the raw Bot API page.





---
title: "Chat & User IDs"
type: summary
tags: [ids, chat-id, user-id, reference]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-bot-api-dialog-ids.md]
---

# Chat & User IDs

A quick reference for the ID conventions bots deal with (a frequent source of confusion).

## ID types

- **User IDs** — positive integers identifying a Telegram user (a bot's own id is part of its token before the `:`).
- **Private chat id** = the user's id (a 1:1 chat with a user uses that user's id as `chat_id`).
- **Group (basic) chat ids** — negative integers.
- **Supergroup & channel ids** — large negatives with a `-100` prefix (e.g. `-100xxxxxxxxxx`). Supergroups/channels are the same id space; the `-100` marks them.

## Size & safety

IDs can exceed 32-bit range; treat them as **64-bit integers** (or strings) to avoid overflow bugs in some languages/JSON parsers.

## Getting an id

- From any [update](../concepts/receiving-updates.md): `message.chat.id`, `message.from.id`.
- For channels/groups, add the bot and read the id from an incoming update, or use `getChat` with a `@username`.
- `@userinfobot`-style helper bots echo ids during development.

## Usernames vs ids

Public chats can be addressed by `@username` in many methods, but **ids are stable** (usernames can change). Store the id, not the username, as the durable key. This reference complements the [bot-api-method-catalog](bot-api-method-catalog.md); the deeper client-side id system is in [client-api-and-tdlib](../concepts/client-api-and-tdlib.md).





---
title: "Bot FAQ & Gotchas Casebook"
type: synthesis
tags: [faq, troubleshooting, gotchas, casebook]
updated: 2026-06-19
confidence: medium
sources: [raw/web_community-bots-faq.md, raw/web_community-marvin-s-marvellous-guide-to-all-things-webhook.md, raw/web_community-telegram-bot-features.md]
---

# Bot FAQ & Gotchas Casebook

Common questions and failure modes from the bot FAQ and webhook guide. Confidence medium — distilled.

## "My bot doesn't see group messages"

**Privacy mode** is on by default: a group bot only receives commands, replies to it, and @mentions. Disable via BotFather (`/setprivacy`) and re-add the bot if you need all messages ([bot-features](../concepts/bot-features.md)).

## Webhook not receiving updates

- HTTPS with a **valid cert** on a **supported port** (443/80/88/8443) ([receiving-updates](../concepts/receiving-updates.md)).
- Check `getWebhookInfo` — it reports the last error and pending update count.
- Don't run polling and a webhook at once; `deleteWebhook` before polling.
- Respond 2xx fast; slow handlers cause retries/duplicates.

## Rate limits / "Too Many Requests"

Responses include `error_code: 429` with `parameters.retry_after` (seconds) — back off. Avoid bursts to one chat (~1 msg/sec per chat as a rule of thumb; broadcasting to many users has stricter aggregate limits). Spread bulk sends.

## File limits

Via `api.telegram.org`: downloads up to 20 MB, uploads up to 50 MB. Need more? Run your own **local Bot API server** ([bot-api](../entities/bot-api.md)).

## Formatting errors

`can't parse entities` means malformed MarkdownV2/HTML — MarkdownV2 requires escaping many characters; prefer HTML or explicit `entities` ([messages-and-formatting](../concepts/messages-and-formatting.md)).

## IDs look wrong / overflow

Channel/supergroup ids are large negatives (`-100…`); treat all ids as 64-bit ([chat-and-user-ids](../summaries/chat-and-user-ids.md)).

## Mini App "user" can't be trusted

Always HMAC-validate `initData` against your bot token server-side before trusting identity ([mini-apps](../concepts/mini-apps.md)).

## Can a bot message a user first?

No — users must **start** the bot (or add it to a group) before it can message them. Use a `t.me/?start=` deep link to onboard ([bot-features](../concepts/bot-features.md)).





---
title: "Building Your First Bot (End to End)"
type: synthesis
tags: [tutorial, getting-started, workflow, synthesis]
updated: 2026-06-19
confidence: high
sources: [raw/web_community-from-botfather-to-hello-world.md, raw/web_community-telegram-bot-features.md, raw/web_community-marvin-s-marvellous-guide-to-all-things-webhook.md]
---

# Building Your First Bot (End to End)

The full path from nothing to a working bot, tying the concept pages together.

## 1. Create & configure

- `/newbot` with **@BotFather** → get the **token** ([creating-a-bot-with-botfather](../concepts/creating-a-bot-with-botfather.md)).
- Set commands (`/setcommands`), description, and (if needed) disable privacy mode for groups.

## 2. Choose how to receive updates

- **Development**: long polling (`getUpdates`) — no server needed.
- **Production**: a webhook (`setWebhook`) on an HTTPS endpoint (ports 443/80/88/8443), secured with a `secret_token` ([receiving-updates](../concepts/receiving-updates.md)).

## 3. Handle the core loop

For each [Update](../concepts/receiving-updates.md): inspect its type (`message`, `callback_query`, `inline_query`, …), branch on commands or content, and respond with a `send*`/`answer*` method. Keep a small state store keyed by [chat/user id](../summaries/chat-and-user-ids.md).

## 4. Build the interface

- Menus and flows with [keyboards](../concepts/keyboards-and-interface.md) — reply keyboards for simple menus, inline keyboards + `callback_query` for app-like in-place navigation.
- Rich content and [formatting](../concepts/messages-and-formatting.md) (HTML/MarkdownV2).
- For a full UI, embed a [Mini App](../concepts/mini-apps.md) (validate `initData`!).

## 5. Add capabilities as needed

[Inline mode](../concepts/inline-mode.md) to work in any chat; [payments/Stars](../concepts/payments-and-stars.md) to monetize; [games](../concepts/games.md) for arcade content.

## 6. Use a library

Many production bots use a wrapper library rather than calling the raw HTTP API by hand — common options include python-telegram-bot, aiogram (Python), and Telegraf/grammY (JS) — which handle update dispatch, retries, and types. They mirror the [Bot API](../entities/bot-api.md) method names, so the [method catalog](../summaries/bot-api-method-catalog.md) maps directly.

## Common first-bot mistakes

Leaking the token; forgetting to `deleteWebhook` before switching to polling (or vice versa); not answering `callback_query`/`pre_checkout_query` (users see a spinner); 32-bit id overflow; not validating Mini App `initData`. See [bot-faq-casebook](bot-faq-casebook.md).