{"id":13486156,"url":"https://github.com/tdlight-team/tdlight-telegram-bot-api","last_synced_at":"2025-03-27T20:32:10.186Z","repository":{"id":41303050,"uuid":"310030106","full_name":"tdlight-team/tdlight-telegram-bot-api","owner":"tdlight-team","description":"The TDLight Telegram Bot API is an actively enhanced fork of the original Bot API, featuring experimental user support, proxies, unlimited files size, and more.","archived":false,"fork":true,"pushed_at":"2024-04-20T19:37:51.000Z","size":16721,"stargazers_count":123,"open_issues_count":16,"forks_count":26,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-08-01T18:25:51.253Z","etag":null,"topics":["mtproto","tdlib","tdlight","telegram","telegram-api","telegram-bot","telegram-bot-api","telegram-bots","telegrambot"],"latest_commit_sha":null,"homepage":"https://t.me/TDLight","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tdlib/telegram-bot-api","license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tdlight-team.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE_1_0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-04T14:41:40.000Z","updated_at":"2024-07-29T09:14:12.000Z","dependencies_parsed_at":"2023-01-31T22:30:46.761Z","dependency_job_id":null,"html_url":"https://github.com/tdlight-team/tdlight-telegram-bot-api","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdlight-team%2Ftdlight-telegram-bot-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdlight-team%2Ftdlight-telegram-bot-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdlight-team%2Ftdlight-telegram-bot-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdlight-team%2Ftdlight-telegram-bot-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tdlight-team","download_url":"https://codeload.github.com/tdlight-team/tdlight-telegram-bot-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222313727,"owners_count":16965367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mtproto","tdlib","tdlight","telegram","telegram-api","telegram-bot","telegram-bot-api","telegram-bots","telegrambot"],"created_at":"2024-07-31T18:00:40.567Z","updated_at":"2024-10-30T21:31:01.386Z","avatar_url":"https://github.com/tdlight-team.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# TDLight Telegram Bot API\nThe official documentation is [here](https://tdlight-team.github.io/tdlight-telegram-bot-api/).\n\nTDLight Telegram Bot API is an actively enhanced fork of the original Bot API, featuring experimental user support, proxies, unlimited files size, and more.\n\nTDLight Telegram Bot API is 100% compatible with the official version.\n\nThe Telegram Bot API provides an HTTP API for creating [Telegram Bots](https://core.telegram.org/bots).\n\nIf you've got any questions about bots or would like to report an issue with your bot, kindly contact [@BotSupport](https://t.me/BotSupport) in Telegram.\n\nIf you've got any questions about our fork, instead, join [@TDLightChat](https://t.me/TDLightChat) in Telegram, or see the news at [@TDLight](https://t.me/TDLight).\n\nPlease note that only TDLight-specific issues are suitable for this repository.\n\n## Table of Contents\n- [TDLight Bot API features](#tdlight-features)\n    - [Added features](#added-features)\n      - [Added API Methods](#added-api-methods)\n      - [Added Command Line Parameters](#added-command-line-parameters)\n    - [Modified features](#modified-features)\n    - [User Mode](#user-mode)\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [Usage](#usage)\n- [Documentation](#documentation)\n- [Moving a bot to a local server](#switching)\n- [Moving a bot from one local server to another](#moving)\n- [License](#license)\n\n\u003ca name=\"tdlight-features\"\u003e\u003c/a\u003e\n## TDLight Bot API features\n\n\u003ca name=\"added-features\"\u003e\u003c/a\u003e\n### Added features\n\n\u003ca name=\"added-api-methods\"\u003e\u003c/a\u003e\n##### Method `getMessageInfo`\nGet information about a message\n###### Parameters\n- `chat_id` Message chat id\n- `message_id` Message id\n###### Returns `message`\n\n Document the following methods:\n##### Method `getParticipants`\nGet the member list of a supergroup or channel\n###### Parameters\n- `chat_id` Chat id\n- `filter` String, possible values are\n    `members`, `parameters`, `admins`, `administators`, `restricted`, `banned`, `bots`\n- `offset` Number of users to skip\n- `limit` The maximum number of users be returned; up to 200\n\n###### Returns `ChatMember`\n\n###### Parameters\n- `chat_id` Chat id\n- `start` First message id to delete\n- `end` Last message id to delete\n###### Returns `true`\n\n##### Command `ping`\nSend an MTProto ping message to the telegram servers.\nUseful to detect the delay of the bot api server.\n\n###### Parameters\nNo parameters\n###### Returns `string`\nPing delay in seconds represented as string.\n\n\u003c!--TODO:\n#### Command `toggleGroupInvites`\n(todo)\n##### Parameters\n- `(todo)`\n##### Returns `(todo)`\n--\u003e\n\n\u003ca name=\"added-command-line-parameters\"\u003e\u003c/a\u003e\n#### Added Command Line Parameters\n##### Flag `--relative`\nIf enabled, allow only relative paths for files in local mode.\n\n##### Flag `--insecure`\nAllow http connection in non-local mode\n\n##### Flag `--max-batch-operations=\u003cnumber\u003e`\nmaximum number of batch operations (default 10000)\n\n##### Executable parameter `--stats-hide-sensible-data`\nMakes the stats page (if enabled) hide the bot token and the webhook url to no leak user secrets, when served publicly.\n\n#### Existing Command Line Parameters\nWhich are not properly documented, so they are written down here.\n\n##### Flag `-v\u003cnumber\u003e`/`--verbose=\u003cnumber\u003e`\nVerbosity of logging.\nThe [loglevels](https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/tdutils/td/utils/logging.h#L103-L109) are\n- `0`: Only fatal errors (least noisy)\n- `1`: All errors\n- `2`: Warnings, too\n- `3`: Infos\n- `4`: Debug output (very spammy)\n- `1024`: Also the stuff which is considered to \"never\" appear (as of writing there's no such stuff).\n_For Docker containers, `$TELEGRAM_VERBOSITY` can be set._\n\n\u003ca name=\"modified-features\"\u003e\u003c/a\u003e\n#### Modified features\n\n##### Method `getChat`\nThe command `getChat` will also try to resolve the username online, if it can't be found locally\n\n##### Method `deleteMessages`\nThe command `deleteMessages` can also delete all the messages with message_id in range between `start` and `end`.  \nThe `start` parameter MUST be less than the `end` parameter  \nBoth `start` and `end` must be positive non-zero numbers  \nThe method will always return `true` as a result, even if the messages cannot be deleted  \nThis method does not work on private chat or normal groups\nIt is not suggested to delete more than 200 messages per call\n\n**NOTE**  \nThe maximum number of messages to be deleted in a single batch is determined by the `max-batch-operations` parameter and is 10000 by default\n\n##### Object `Message`\nThe `Message` object now has two new fields:\n- `views`: how many views has the message (usually the views are shown only for channel messages)\n- `forwards`: how many times the message has been forwarded\n\n##### Object `ChatMember`\nThe `ChatMember` object now has two new fields:\n- `joined_date`: integer, unix timestamp, when has the user joined\n- `inviter`: `User`, the inviter\n\n##### Object `Chat`\nThe `Chat` object now has two new fields:\n- `is_verified`: bool, optional, default false. Is the chat verified by Telegram, clients show a verified batch\n- `is_scam`: bool, optional, default false. Is the chat reported for scam, clients show a warning to the user\n\n##### Object `User`\nThe `User` object now has two new fields:\n- `is_verified`: bool, optional, default false. Is the user verified by Telegram, clients show a verified batch\n- `is_scam`: bool, optional, default false. Is the user reported for scam, clients show a warning to the user\n\nIn addition, the member list now shows the full bot list (previously only the bot that executed the query was shown)\n\nThe bot will now receive Updates for all received media, even if a destruction timer is set.\n\n\u003ca name=\"user-mode\"\u003e\u003c/a\u003e\n### User Mode\n\nYou can allow user accounts to access the bot api with the command-line option `--allow-users` or set the env variable\n`TELEGRAM_ALLOW_USERS` to `1` when using docker. User Mode is disabled by default, so only bots can access the api.\n\nYou can now log into the bot api with user accounts to create userbots running on your account.\n\nNote: Never send your 2fa password over a plain http connection. Make sure https is enabled or use this api locally.\n\n#### User Authorization Process\n1. Send a request to `{api_url}/userlogin`\n\n   Parameters:\n   - `phone_number`: `string`. The phone number of your Telegram Account.\n\n   Returns your `user_token` as `string`. You can use this just like a normal bot token on the `/user` endpoint\n\n2. Send the received code to `{api_url}/user{user_token}/authcode`\n\n   Parameters:\n   - `code`: `int`. The code send to you by Telegram In-App or by SMS\n\n   Will send `{\"ok\": true, \"result\": true}` on success.\n\n3. Optional: Send your 2fa password to `{api_url}/user{user_token}/2fapassword`\n\n   Parameters:\n   - `password`: `string`. Password for 2fa authentication\n\n   Will send `{\"ok\": true, \"result\": true}` on success.\n\n4. Optional: Register the user by calling `{api_url}/user{user_token}/registerUser`.\n\n   User registration is disabled by default. You can enable it with the `--allow-users-registration` command line\n   option or the env variable `TELEGRAM_ALLOW_USERS_REGISTRATION` set to `1` when using docker.\n\n   Parameters:\n   - `first_name`: `string`. First name for the new account.\n   - `last_name`: `string`, optional. Last name for the new account.\n\n   Will send `{\"ok\": true, \"result\": true}` on success.\n\nYou are now logged in and can use all methods like in the bot api, just replace the\n`/bot{bot_token}/` in your urls with `/user{token}/`.\n\nYou only need to authenticate once, the account will stay logged in. You can use the `logOut` method to log out\nor simply close the session in your account settings.\n\nSome methods are (obviously) not available as a user. This includes:\n- `answerCallbackQuery`\n- `setMyCommands`\n- `editMessageReplyMarkup`\n- `uploadStickerFile`\n- `createNewStickerSet`\n- `addStickerToSet`\n- `setStickerPositionInSet`\n- `deleteStickerFromSet`\n- `setStickerSetThumb`\n- `sendInvoice`\n- `answerShippingQuery`\n- `answerPreCheckoutQuery`\n- `setPassportDataErrors`\n- `sendGame`\n- `setGameScore`\n- `getGameHighscores`\n\nIt is also not possible to attach a `reply_markup` to any message.\n\nYour api wrapper may behave different in\nsome cases, for examples command message-entities are not created in chats that don't contain any\nbots, so your Command Handler may not detect it.\n\nIt is possible to have multiple user-tokens to multiple client instances on the same bot api server.\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\n## Installation\n\nThe simplest way to use it is with this docker command:\n```bash\ndocker run -p 8081:8081 --env TELEGRAM_API_ID=API_ID --env TELEGRAM_API_HASH=API_HASH tdlight/tdlightbotapi\n```\n\nThe simplest way to build `Telegram Bot API server` is to use our [Telegram Bot API server build instructions generator](https://tdlight-team.github.io/tdlight-telegram-bot-api/build.html).\nIf you do that, you'll only need to choose the target operating system to receive the complete build instructions.\n\nIn general, you need to install all `Telegram Bot API server` [dependencies](#dependencies) and compile the source code using CMake:\n\n```bash\ngit clone --recursive https://github.com/tdlight-team/tdlight-telegram-bot-api\ncd tdlight-telegram-bot-api\nmkdir build\ncd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build . --target install\n```\n\nIf you forgot that `--recursive` flag at the clone part, you can just navigate into that created folder and run\n```bash\ncd tdlight-telegram-bot-api\ngit submodule update --init --recursive\n```\n\n\u003ca name=\"dependencies\"\u003e\u003c/a\u003e\n## Dependencies\nTo build and run `Telegram Bot API server` you will need:\n\n* OpenSSL\n* zlib\n* C++14 compatible compiler (e.g., Clang 3.4+, GCC 4.9+, MSVC 19.0+ (Visual Studio 2015+), Intel C++ Compiler 17+) (build only)\n* gperf (build only)\n* CMake (3.0.2+, build only)\n* _having it cloned with `--recursive` (see [above](#installation)) to get `tdlib`_\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n## Usage\n\nUse `telegram-bot-api --help` to receive the list of all available options of the Telegram Bot API server.\n\nThe only mandatory options are `--api-id` and `--api-hash`. You must obtain your own `api_id` and `api_hash`\nas described in https://core.telegram.org/api/obtaining_api_id and specify them using the `--api-id` and `--api-hash` options\nor the `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` environment variables.\n\nTo enable Bot API features not available at `https://api.telegram.org`, specify the option `--local`. In the local mode the Bot API server allows to:\n* Download files without a size limit.\n* Upload files up to 2000 MB.\n* Upload files using their local path and [the file URI scheme](https://en.wikipedia.org/wiki/File_URI_scheme).\n* Use an HTTP URL for the webhook.\n* Use any local IP address for the webhook.\n* Use any port for the webhook.\n* Set *max_webhook_connections* up to 100000.\n* Receive the absolute local path as a value of the *file_path* field without the need to download the file after a *getFile* request.\n\nThe Telegram Bot API server accepts only HTTP requests, so a TLS termination proxy needs to be used to handle remote HTTPS requests.\n\nBy default the Telegram Bot API server is launched on the port 8081, which can be changed using the option `--http-port`.\n\n\u003ca name=\"documentation\"\u003e\u003c/a\u003e\n## Documentation\nSee [Bots: An introduction for developers](https://core.telegram.org/bots) for a brief description of Telegram Bots and their features.\n\nSee the [Telegram Bot API documentation](https://core.telegram.org/bots/api) for a description of the Bot API interface and a complete list of available classes, methods and updates.\n\nSee the [Telegram Bot API server build instructions generator](https://tdlib.github.io/telegram-bot-api/build.html) for detailed instructions on how to build the Telegram Bot API server.\n\nSubscribe to [@BotNews](https://t.me/botnews) to be the first to know about the latest updates and join the discussion in [@BotTalk](https://t.me/bottalk).\n\n\u003ca name=\"switching\"\u003e\u003c/a\u003e\n## Moving a bot to a local server\n\nTo guarantee that your bot will receive all updates, you must deregister it with the `https://api.telegram.org` server by calling the method [logOut](https://core.telegram.org/bots/api#logout).\nAfter the bot is logged out, you can replace the address to which the bot sends requests with the address of your local server and use it in the usual way.\nIf the server is launched in `--local` mode, make sure that the bot can correctly handle absolute file paths in response to `getFile` requests.\n\n\u003ca name=\"moving\"\u003e\u003c/a\u003e\n## Moving a bot from one local server to another\n\nIf the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates.\nTo move a bot from one local server to another you can use the method [logOut](https://core.telegram.org/bots/api#logout) to log out on the old server before switching to the new one.\n\nIf you want to avoid losing updates between logging out on the old server and launching on the new server, you can remove the bot's webhook using the method\n[deleteWebhook](https://core.telegram.org/bots/api#deletewebhook), then use the method [close](https://core.telegram.org/bots/api#close) to close the bot instance.\nAfter the instance is closed, locate the bot's subdirectory in the working directory of the old server by the bot's user ID, move the subdirectory to the working directory of the new server\nand continue sending requests to the new server as usual.\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n`Telegram Bot API server` source code is licensed under the terms of the Boost Software License. See [LICENSE_1_0.txt](http://www.boost.org/LICENSE_1_0.txt) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdlight-team%2Ftdlight-telegram-bot-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftdlight-team%2Ftdlight-telegram-bot-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdlight-team%2Ftdlight-telegram-bot-api/lists"}