Telegram Bot API Server

To migrate a bot from one local server to another while minimizing update loss:

1. Call deleteWebhook to remove the bot's webhook.
2. Call close to close the bot instance on the old server.
3. Locate the bot's subdirectory in the old server's working directory (named by the bot's user ID).
4. Move that subdirectory to the working directory of the new server.
5. Resume sending requests to the new server.

To build and install the Telegram Bot API server, you can use the Telegram Bot API server build instructions generator for your specific operating system.

Alternatively, you can manually compile the source code using CMake following these steps:

1. Clone the repository recursively.
2. Create a build directory.
3. Run CMake to configure the build type as Release.
4. Build and install the target.

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

The Telegram Bot API server requires two mandatory credentials obtained from Telegram: api_id and api_hash. These can be provided via command-line options or environment variables.

Mandatory Options/Environment Variables:

• --api-id or TELEGRAM_API_ID
• --api-hash or TELEGRAM_API_HASH

Common Configuration:

• --http-port: Changes the default port (default is 8081).
• --local: Enables local mode to unlock advanced features (see below).
• --help: Displays all available options.

Note: The server only accepts HTTP requests. To handle remote HTTPS requests, you must use a TLS termination proxy.

To ensure your bot receives all updates when switching from the official Telegram servers to your local server:

1. Call the logOut method to deregister the bot from https://api.telegram.org.
2. Redirect your bot's request address to your local server.
3. If using --local mode, ensure your bot is configured to handle absolute file paths returned by getFile requests.

By specifying the --local option, the Telegram Bot API server enables features not available on the standard https://api.telegram.org endpoint:

• File Handling:
  • Download files without a size limit.
  • Upload files up to 2000 MB.
  • Upload files using local paths and the file URI scheme.
  • Receive absolute local paths in the file_path field of a getFile response (avoiding the need to download the file).
• Webhooks:
  • 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 100,000.

The following dependencies are required:

Runtime Dependencies:

• OpenSSL
• zlib

Build-time Dependencies:

• C++17 compatible compiler (e.g., Clang 5.0+, GCC 7.0+, MSVC 19.1+, Intel C++ Compiler 19+)
• gperf
• CMake (3.10+)

Use get_message(int64 chat_id, int64 message_id, bool force_cache) to retrieve cached information about a specific message.

MessageInfo contains:

• id, chat_id, sender_user_id, sender_chat_id.
• date, edit_date.
• content: object_ptr<td_api::MessageContent>.
• reply_to_message: object_ptr<td_api::messageReplyToMessage>.
• reply_markup: object_ptr<td_api::ReplyMarkup>.
• is_outgoing, is_self_destruct, is_scheduled, is_paid_post.
• topic_id: object_ptr<td_api::MessageTopic>.

The Client interface provides methods to manage the bot's webhook settings:

• do_set_webhook(PromisedQueryPtr query, bool was_deleted): Initiates setting or deleting a webhook.
• get_webhook_certificate(const Query *query): Returns a pointer to the td::HttpFile containing the webhook certificate.
• get_webhook_max_connections(const Query *query): Returns the maximum number of connections.
• get_webhook_certificate_path(): Returns the path to the webhook certificate.
• save_webhook(): Persists the current webhook configuration.

Webhook lifecycle callbacks include webhook_verified, webhook_success, webhook_error, and webhook_closed.

The telegram_bot_api::Client class is the primary interface for interacting with the Telegram Bot API server. It manages queries, handles updates, and provides utility methods for extracting data from incoming queries.

Key capabilities include:

• Sending queries via send(PromisedQueryPtr query).
• Retrieving bot information via get_bot_info().
• Handling asynchronous results through various on_... callback methods.
• Extracting specific arguments (like user_id, message_id, or chat_id) from a Query object using static helper methods.

Use get_chat(int64 chat_id) to retrieve cached information about a chat.

ChatInfo contains:

• type: Private, Group, Supergroup, or Unknown.
• title.
• message_auto_delete_time.
• has_protected_content.
• permissions: object_ptr<td_api::chatPermissions>.
• photo_info: object_ptr<td_api::chatPhotoInfo>.
• A union containing user_id, group_id, or supergroup_id depending on the type.

Use get_integer_arg to retrieve an integer value from a specific field in a Query, with optional bounds checking.

static int32 get_integer_arg(const Query *query, td::Slice field_name, int32 default_value, 
                               int32 min_value = std::numeric_limits<int32>::min(), 
                               int32 max_value = std::numeric_limits<int32>::max());