The Telegram Bot API provides an HTTP API for creating Telegram Bots.


Telegram Bot API

The Telegram Bot API provides an HTTP API for creating Telegram Bots.

If you've got any questions about bots or would like to report an issue with your bot, kindly contact us at @BotSupport in Telegram.

Please note that only global Bot API issues that affect all bots are suitable for this repository.

Table of Contents


The simplest way to build and install Telegram Bot API server is to use our Telegram Bot API server build instructions generator. If you do that, you'll only need to choose the target operating system to receive the complete build instructions.

In general, you need to install all Telegram Bot API server dependencies and compile the source code using CMake:

git clone --recursive
cd telegram-bot-api
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target install


To build and run Telegram Bot API server you will need:

  • OpenSSL
  • zlib
  • C++14 compatible compiler (e.g., Clang 3.4+, GCC 4.9+, MSVC 19.0+ (Visual Studio 2015+), Intel C++ Compiler 17+) (build only)
  • gperf (build only)
  • CMake (3.0.2+, build only)


Use telegram-bot-api --help to receive the list of all available options of the Telegram Bot API server.

The only mandatory options are --api-id and --api-hash. You must obtain your own api_id and api_hash as described in and specify them using the --api-id and --api-hash options or the TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables.

To enable Bot API features not available at, specify the option --local. In the local mode the Bot API server allows to:

  • Download files without a size limit.
  • Upload files up to 2000 MB.
  • Upload files using their local path and the file URI scheme.
  • Use an HTTP URL for the webhook.
  • Use any local IP address for the webhook.
  • Use any port for the webhook.
  • Set max_webhook_connections up to 100000.
  • Receive the absolute local path as a value of the file_path field without the need to download the file after a getFile request.

The Telegram Bot API server accepts only HTTP requests, so a TLS termination proxy needs to be used to handle remote HTTPS requests.

By default the Telegram Bot API server is launched on the port 8081, which can be changed using the option --http-port.


See Bots: An introduction for developers for a brief description of Telegram Bots and their features.

See the Telegram Bot API documentation for a description of the Bot API interface and a complete list of available classes, methods and updates.

See the Telegram Bot API server build instructions generator for detailed instructions on how to build the Telegram Bot API server.

Subscribe to @BotNews to be the first to know about the latest updates and join the discussion in @BotTalk.

Moving a bot to a local server

To guarantee that your bot will receive all updates, you must deregister it with the server by calling the method logOut. After 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. If the server is launched in --local mode, make sure that the bot can correctly handle absolute file paths in response to getFile requests.

Moving a bot from one local server to another

If the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates. To move a bot from one local server to another you can use the method logOut to log out on the old server before switching to the new one.

If 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 deleteWebhook, then use the method close to close the bot instance. After 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 and continue sending requests to the new server as usual.


Telegram Bot API server source code is licensed under the terms of the Boost Software License. See LICENSE_1_0.txt for more information.

  • Bot api server general questions

    Bot api server general questions

    1. Is it right that this is bot-api to client-api proxy for bots?
    2. Can we extend this server api with methods that exist in client api and can be called by bots but does not exist in bot api?
    opened by Fedorus 58
  • should it be dockerized?

    should it be dockerized?

    Awesome! If someone would be run bot-api on cloud native environment pull requests with Dockerfiles will be accepted or users must implement it on their side?

    opened by cybervagabond 25
  • How to use multi-core CPU?

    How to use multi-core CPU?

    My server has an 8-core CPU. Currently, only 1 CPU is used, and the other 7 are idle. I hope to reply, thank you!

    DURATION inf 5sec 1min 1hour uptime 2482.520765 bot_count 4379 active_bot_count 150 rss 18GB vm 18GB rss_peak 18GB vm_peak 18GB total_cpu 118.269319% 113.913043% 114.552656% 118.269319% user_cpu 99.416224% 100.347826% 99.993907% 99.416224% system_cpu 18.853095% 13.565217% 14.558749% 18.853095% buffer_memory 3040MB active_webhook_connections 3281 active_requests 174706 active_network_queries 172347 request_count 614.006956 364.547365 294.479924 614.006956 request_bytes 271470.504437 166391.486635 129315.445543 271470.504468 request_file_count 0.000000 0.000000 0.000000 0.000000 request_files_bytes 0.000000 0.000000 0.000000 0.000000 request_max_bytes 0 0 0 0 response_count 543.640529 347.578607 347.736007 543.640529 response_count_ok 76.525494 107.880848 70.113676 76.525494 response_count_error 467.115035 239.697759 277.622331 467.115035 response_bytes 136281.333011 162937.389112 112554.637102 136281.333026 update_count 1348.788008 1905.333100 2052.825080 1348.788008

    opened by mylukin 17
  • Timeout in

    Timeout in

    Hello! I am making small bot-api server based on MTProto. In some cases i use When i revoke token and re-call its hangs my code i thought i have a problem with my code but when i check logs i found that its hangs on starting new https connection to after some seconds its returns 504 Gateway Timeout . Means if i have new Token and call in the first request i get 504 Gateway Timeout in the second request i get 200 OK

    Sorry for the bad explanation 😅

    opened by AYMENJD 17
  • how to build cross platform?

    how to build cross platform?

    I tried to build for android on linux debian 10 intel 64 bit but there is a failure

    I have installed all the required packages but when I type this command a log appears

    cmake -DCMAKE_BUILD_TYPE=Release ..

    error log

    -- Could NOT find ZLIB (missing: ZLIB_LIBRARY) (found version "1.2.11")
    -- Could NOT find ZLIB (missing: ZLIB_LIBRARY) (found version "1.2.11")
    CMake Warning at td/CMakeLists.txt:181 (message):
      Can't find zlib: stop TDLib building
    CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
    Please set them or make sure they are set and tested correctly in the CMake files:
        linked by target "tdutils" in directory /home/azka/telegram-bot-api/td/tdutils
    -- Configuring incomplete, errors occurred!
    See also "/home/azka/telegram-bot-api/build/CMakeFiles/CMakeOutput.log".
    See also "/home/azka/telegram-bot-api/build/CMakeFiles/CMakeError.log".
    opened by azkadev 16
  • Tdlib vs Bot-API

    Tdlib vs Bot-API

    Hi, I have a question about also tdlib.

    I have my high loaded bot 100 update per second i am sure in weekend 100+ update per second Its group management bot

    I want to rebuild the bot source but I'm confused what to use Tdlib or webhook, Who better?

    If i use Tdlib will use more memory and more disk space (i try to login using my bot in the first 5 minutes db.sqlite gets 55M size)

    If i use will be lot easier dealing with updates but i will lose access to some methods that not available on Bot-API like get user information by username etc and i need that .

    I can use two instance and MTProto Client (for other methods not available on Bot-API) I don't think is the right way to use that.

    @levlam If it was you, what would you choose and why?

    opened by AYMENJD 15
  • Upload file error: EOF

    Upload file error: EOF

    An EOF error occurs when I upload a file that is larger than about 1GB(local mode), even though the file is still sent successfully. This doesn't happen when I send files around 500MB. The POST request returns to the EOF about halfway through the file, but the request has been interrupted. After the result is returned, the file is still sent by the API.

    opened by ghost 15
  • Request documenting the behavior of `MessageEntity` type `text_mention` when sending messages

    Request documenting the behavior of `MessageEntity` type `text_mention` when sending messages


    After some testing, we can use MessageEntity's text_mention type to mention users when sending messages, and the required fields of user are id only. But this behavior is undocumented, may we document it?

    opened by SpriteOvO 14
  • `ChatMemberBanned` `until_date` is 0

    `ChatMemberBanned` `until_date` is 0

    I receive "until_date": 0 in ChatMemberBanned object for banned forever users, which doesn't make sense. Is this intentional behaviour? Could this field be optional for such occurrences?

    opened by karb0f0s 14
  • False attack detection based on

    False attack detection based on "\n" after "update_id"

    Hello, I've created a bot for interacting with my website (displaying flights data). after activating the bot, and running it successfully, I got many errors on my web servers' log: "HTTP Header Injection Attack via payload (CR/LF detected)"

    I've done some digging and I believe the source is the "\n" here: "ARGS_NAMES:{"update_id":38xxxxxxx,\n"message":{"message_id":3xxx, ..." (after the "update_id" and before the "message") If I'm not mistaken, the LineFeed mark is generated in "telegram-bot-api/WebhookActor.h", line 217 : object << td::JsonRaw(",\n");

    Is the "\n" a part of a mandatory args structure? Is there a way to remove it? Any other suggestion?

    opened by JTS-IL 13
  • low speed of robots

    low speed of robots

    Hi. I've install telegram-bot-api on my server based on "Telegram Bot API server build instructions generator" part with clang compiler in /usr/local directory and run it with this command :

    telegram-bot-api --api-id=... --api-hash=... --local --dir=/var/log/tg --max-webhook-connections=100000 --log=/var/log/tg/ --max-connections=1000

    (api id and api hash that i wroted is fake). so then i changed the telegram api of the source of my bot (php) to the ip address of my server. I loged out the bot with logOut method, too. now some part of my bot work fast and some part have 1 ~ 2 second delay for responsing. I tried to examine the source code and requests and i find out that the handling requests with sendmessage method that have short text are faster than longer one. How can i fix it? Is there any misconfiguration while running telegram-bot-api?

    I use it on server with 3 Gb of ram and 3 core of cpu (3.07Ghz). operating system : ubuntu 18 webserver : apache

    note that I don't use ssl with domain . I use ip address and port number for sending requests and setwebhook.

    opened by GoldExynos 13
  • Cannot download file in local mode

    Cannot download file in local mode

    I setted up nginx server as in aiogram/telegram-bot-api/example repo. Without local mode files downloading without any problems but when I turn local mode on bot returns this error: aiohttp.client_exceptions.ClientResponseError: 404, message='Not Found', url=URL('http://localhost:80/file/bot<token>//var/lib/telegram-bot-api/<token>/documents/file_3.p12')

    opened by d-idea 5
  • file is too big on getFile with local bot api

    file is too big on getFile with local bot api

    Hi, I have a problem with telegram bot server on my server. I have created a service in Linux Ubuntu for telegram bot api with this details:

    `[Unit] Description=Telegram bot api on Ubuntu

    [Service] #WorkingDirectory=/root/telegram-bot-api/bin ExecStart=/root/telegram-bot-api/bin/telegram-bot-api --local --api-id=12345 --api-hash=[my hash id] Restart=always RestartSec=10 # Restart service after 10 seconds if dotnet service crashes SyslogIdentifier=telegram-bot-api-service



    When I call getFile api with this data, I got Bad Request: file is too big.


    Is there any solution for this problem?

    opened by idotnetdev 5
  • Customizing amount of timeout for local servers

    Customizing amount of timeout for local servers

    Is it possible for you to add a option for customizing longer timeout at least for local servers? The default is 30 seconds, I find myself in some situations like encoding a long video for the user need longer than 30 seconds.

    opened by foremtehan 3
  • Inconvenient way to handle Media Groups

    Inconvenient way to handle Media Groups

    What's the problem

    I ran into a problem with handling media group messages, in other words — messages with multiple medias attached. The current version of bot API sends each media in a separate message and adds mediaGroupID to it, which makes sense since each media can have their own caption.

    However, it makes a problem when you try to handle a whole group and store it, for instance. That happens because the code doesn't know when sending media group stops, only which message belong to media group and which not.

    The only way I see is to make a timer, like for a second, during which the bot will look for messages with specific mediaGroupID. After the expiration of time, if no other message with mediaGroupID sent, the timer stops. Obviously, this is a terrible solution, so there should be another way to do it (if you have some idea, feel free to write them below).

    How to solve a problem

    To solve this problem, just let the bot know how much messages a group contains. There are two ways how to do it:

    • Put number of messages in group right into API response, next to the mediaGroupID for each message from the group;
    • Create new method, that receives a mediaGroupID and returns a number of messages in group, like that:<token>/mediaGroupSize?media_group_id=<your id>
    opened by OwnMind-ai 3
Telegram Library
Telegram Library
H2O - the optimized HTTP/1, HTTP/2, HTTP/3 server

H2O - an optimized HTTP server with support for HTTP/1.x, HTTP/2 and HTTP/3 (experimental) Copyright (c) 2014-2019 DeNA Co., Ltd., Kazuho Oku, Tatsuhi

H2O 10.2k Dec 30, 2022
C++ library for creating an embedded Rest HTTP server (and more)

The libhttpserver reference manual Tl;dr libhttpserver is a C++ library for building high performance RESTful web servers. libhttpserver is built upon

Sebastiano Merlino 711 Dec 27, 2022
tiny HTTP parser written in C (used in HTTP::Parser::XS et al.)

PicoHTTPParser Copyright (c) 2009-2014 Kazuho Oku, Tokuhiro Matsuno, Daisuke Murase, Shigeo Mitsunari PicoHTTPParser is a tiny, primitive, fast HTTP r

H2O 1.6k Jan 1, 2023
A collection of C++ HTTP libraries including an easy to use HTTP server.

Proxygen: Facebook's C++ HTTP Libraries This project comprises the core C++ HTTP abstractions used at Facebook. Internally, it is used as the basis fo

Facebook 7.7k Jan 4, 2023
Pushpin is a reverse proxy server written in C++ that makes it easy to implement WebSocket, HTTP streaming, and HTTP long-polling services.

Pushpin is a reverse proxy server written in C++ that makes it easy to implement WebSocket, HTTP streaming, and HTTP long-polling services. The project is unique among realtime push solutions in that it is designed to address the needs of API creators. Pushpin is transparent to clients and integrates easily into an API stack.

Fanout 3.2k Jan 2, 2023
cuehttp is a modern c++ middleware framework for http(http/https)/websocket(ws/wss).

cuehttp 简介 cuehttp是一个使用Modern C++(C++17)编写的跨平台、高性能、易用的HTTP/WebSocket框架。基于中间件模式可以方便、高效、优雅的增加功能。cuehttp基于boost.asio开发,使用picohttpparser进行HTTP协议解析。内部依赖了nl

xcyl 29 Dec 17, 2022
Gromox - Groupware server backend with MAPI/HTTP, RPC/HTTP, IMAP, POP3 and PHP-MAPI support for grommunio

Gromox is the central groupware server component of grommunio. It is capable of serving as a replacement for Microsoft Exchange and compatibles. Conne

grommunio 139 Dec 26, 2022
Cross-platform library for building Telegram clients

TDLib (Telegram Database library) is a cross-platform library for building Telegram clients. It can be easily used from almost any programming language.

Telegram Library 5.3k Jan 8, 2023
An unofficial Qt-based client for Telegram messenger.

Kutegram How to build Symbian^1 (also Symbian^3) Clone this repository with submodules. git clone --recursive c

Kutegram 18 Sep 22, 2022
Like libevent and libuv, libhv provides event-loop with non-blocking IO and timer, but simpler api and richer protocols.

中文版 Intro Like libevent, libev, and libuv, libhv provides event-loop with non-blocking IO and timer, but simpler api and richer protocols. Features cr

ithewei 5k Jan 4, 2023
Mongoose Embedded Web Server Library - a multi-protocol embedded networking library with TCP/UDP, HTTP, WebSocket, MQTT built-in protocols, async DNS resolver, and non-blocking API.

Mongoose - Embedded Web Server / Embedded Networking Library Mongoose is a networking library for C/C++. It implements event-driven non-blocking APIs

Cesanta Software 9k Jan 1, 2023
C++ API: http server with local dynamic or precompiled repository containers

libnavajo Framework to develop easily web interfaces in your C++ applications Libnavajo makes it easy to run an HTTP server into your own application,

null 60 Jan 29, 2022
Neon - neon - an HTTP/1.1 and WebDAV client library with a C API

neon neon is an HTTP and WebDAV client library, with a C language API. Mailing list: [email protected] || Web site:

Joe Orton 88 Dec 31, 2022
Creating a server-client application with C sockets.

C-ServerClient Creating a server-client application with C socket. How to use? Clone the project and cd in to the main directory. Open a terminal and

AmirH.Najafizadeh 9 Oct 2, 2022
GNOME Shell provides core user interface functions for the GNOME 3 desktop

GNOME Shell GNOME Shell provides core user interface functions for the GNOME 3 desktop, like switching to windows and launching applications. GNOME Sh

Muqtadir 3 Oct 18, 2021
Webdav-client-cpp - C++ WebDAV Client provides easy and convenient to work with WebDAV-servers.

WebDAV Client Package WebDAV Client provides easy and convenient to work with WebDAV-servers: Yandex.Disk Dropbox Google Drive Box 4shared ownCloud ..

Cloud Polis 103 Jan 1, 2023
This repository provides a C++ client SDK for Unleash that meets the Unleash Client Specifications.

Unleash Client SDK for C++ This repository provides a C++ client SDK for Unleash that meets the Unleash Client Specifications. Features The below tabl

Antonio Ruiz 4 Jan 30, 2022
Level up your Beat Saber experience on Quest! AnyTweaks provides various tweaks to help boost your experience on Quest, such as Bloom, FPS Counter and more.

Need help/support? Ask in one of BSMG's support channels for Quest, or join my Discord server! AnyTweaks Level up your Beat Saber experience on Quest!

kaitlyn~ 19 Nov 20, 2022