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

Overview

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

Installation

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 https://github.com/tdlib/telegram-bot-api.git
cd telegram-bot-api
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target install

Dependencies

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)

Usage

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 https://core.telegram.org/api/obtaining_api_id 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 https://api.telegram.org, 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.

Documentation

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 https://api.telegram.org 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.

License

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

Comments
  • 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 api.telegram.org

    Timeout in api.telegram.org

    Hello! I am making small bot-api server based on MTProto. In some cases i use api.telegram.org/getme. When i revoke token and re-call api.telegram.org/getme 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 api.telegram.org/bot../getme after some seconds its returns api.telegram.org/bot../getme 504 Gateway Timeout . Means if i have new Token and call api.telegram.org 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:
    ZLIB_LIBRARY
        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 https://api.telegram.org 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 api.telegram.org 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 api.telegram.org 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 api.telegram.org 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

    Context: https://github.com/teloxide/teloxide/issues/547

    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/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
  • getChatMember method does not work

    getChatMember method does not work

    Hi! I am trying to call getChatMember api to know if the user who entered the bot has joined my telegram channel so that then I can send him a link to free checklist. And whenever I pass user_id which is 298499497 in my case, the api gives me the error - user not found.

    Do you know why it is happening?

    opened by zhvarikk 3
  • [Fetaure request] add grpc support to bot api

    [Fetaure request] add grpc support to bot api

    https://grpc.io/

    Some of great features which is very useful for bots:

    • No need to search docs in browser it can be used with server reflection (More info

    • Two way messaging which is very good for bots and chats (streams)

    • Can group similar methods in services

    • Can create multi stream connections

    • Easy to use

    • Can generate library to any language with .proto files

    And many more

    My proposal: create a grpc service for mesages

    • some methods
    • sendMessage
    • sendVideo ...
    • sendContact

    And one stream for listening to groups and user messages

    • subscribeMessages

    and one for channels

    • subsribeChannelMessages
    opened by smaznet 2
  • How to write own Telegram bot API library?

    How to write own Telegram bot API library?

    Hello! I'm a Lisp programmer and wee haven't got a Telegram bot API library. I want to wright it. It's my questions:

    1. In documentations I saw a lot of available types. Do I need to write classes to all of them?
    2. Can you tall my about architecture of library? What classes are being used and so. Thanks!
    opened by Filipp-Druan 3
  • Prebuilt binaries

    Prebuilt binaries

    Are prebuilt binaries for the common platforms (Windows/Mac/Linux) available anywhere? If not, would a PR adding GitHub action workflows for automatically building them on each commit be welcome?

    opened by KartikSoneji 5
  • Video upload on very slow connection causes network error 104

    Video upload on very slow connection causes network error 104

    I'm currently have to use internet connection with very low upload speed - about 250 kbps. I can upload files using official telegram client, however when I use bot API I very frequently getting error 104.

    Can I do something about it?

    opened by Amomum 3
Owner
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 Nov 27, 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 705 Nov 28, 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 Dec 4, 2022
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 Nov 25, 2022
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 Nov 24, 2022
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 28 Nov 18, 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 130 Nov 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.2k Nov 27, 2022
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 https://github.com/kutegram/client.git 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 4.9k Dec 3, 2022
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 Dec 2, 2022
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: https://notroj.github.io/n

Joe Orton 83 Nov 3, 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 102 Oct 1, 2022
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