Show

tgbotxx

Telegram Bot C++ Library

Compatible with Telegram Bot API 6.9 (September 22, 2023)

CI Status

Operating system	Build status
Ubuntu (x64)
Windows (x64)
macOS

Examples

see examples for more

Example	Description	Preview
WeatherBot	Bot that displays the weather information of a city using the weather api.
EarthquakeBot	Bot that will alert you if there is a recent earthquake somewhere in the world.
QrCodeBot	Bot that can generate QrCode images from text and extract text from QrCode Images.
UrlShortenerBot	Bot for shortening URLs.
Inline Buttons	Bot that uses inline keyboard buttons to interact with users.
Keyboard Buttons	Bot that uses keyboard buttons to interact with users.
PaidSubscriptionBot	Bot that offers it's services for a paid subscription.
ThreadPoolBot	Bot that uses a ThreadPool to handle thousands of requests simultaneously.

Basic sample

see examples for more

#include <tgbotxx/tgbotxx.hpp>
#include <iostream>
using namespace tgbotxx;
 
class MyBot : public Bot {
public:
  MyBot() : Bot("BOT_TOKEN_FROM_BOT_FATHER") {}
    
private:
  void onStart() override {
    // Called before Bot starts receiving updates
    // Initialize your code here...
    std::cout << "Bot Started\n";
  }
  void onStop() override {
    // Called before Bot shuts down (triggered by Bot::stop())
    // Cleanup your code here
    std::cout << "Bot Stopped\n";
  }
  void onAnyMessage(const Ptr<Message>& message) override {
    // Called when Bot receives a new message of any kind
    // NB: a Ptr<T> is just an alias to std::shared_ptr<T>
    api()->sendMessage(message->chat->id, "Hi " + message->from->firstName + "!, got your message!");
  }
  // override other callbacks if needed... 
};
 
int main() {
  MyBot bot;
  bot.start();
  return 0;
}

Extensive sample

Creating a new Bot called MyBot that overrides all callbacks: <details>

#include <tgbotxx/tgbotxx.hpp>
#include <iostream>
using namespace tgbotxx;
 
class MyBot : public Bot {
public:
    MyBot() : Bot("BOT_TOKEN_FROM_BOT_FATHER") {}
 
private:
    void onStart() override {
      // Drop awaiting updates (when Bot is not running, updates will remain 24 hours
      // in Telegram server before they get deleted or retrieved by BOT)
      api()->deleteWebhook(true);
 
      // Register bot commands ...
      Ptr<BotCommand> greet(new BotCommand());
      greet->command = "greet";
      greet->description = "This command will greet you";
      Ptr<BotCommand> stop(new BotCommand());
      stop->command = "stop";
      stop->description = "Stop the bot";
      api()->setMyCommands({greet, stop}); // The above commands will be shown in the bot chat menu (bottom left)
      
      std::cout << "Bot " << api()->getMe()->username << " Started\n";
    }
    
    void onStop() override {
      std::cout << "Bot " << api()->getMe()->username << " Stopped\n";
    }
    
    void onAnyMessage(const Ptr<Message>& message) override {
        api()->sendMessage(message->chat->id, "Hi " + message->from->firstName + "!, got your message!");
    }
    
    void onCommand(const Ptr<Message>& message) override {
      if(message->text == "/stop") {
        api()->sendMessage(message->chat->id, "Bot stopping...");
        Bot::stop();
        return;
      }
    }
    
    void onLongPollError(const std::string& errorMessage, ErrorCode errorCode) override {
      std::cerr <<  "Long polling error: " << errorMessage << ". Error code: " << errorCode << std::endl;
    }
    
    void onNonCommandMessage(const Ptr<Message>& message) override {}
    
    void onUnknownCommand(const Ptr<Message>& message) override {}
 
    void onEditedMessage(const Ptr<Message>& editedMessage) override {}
 
    void onMessageReactionUpdated(const Ptr<MessageReactionUpdated>& messageReaction) override {}
 
    void onMessageReactionCountUpdated(const Ptr<MessageReactionCountUpdated>& messageReactionCount) override {}
 
    void onInlineQuery(const Ptr<InlineQuery>& inlineQuery) override {}
 
    void onChosenInlineResult(const Ptr<ChosenInlineResult>& chosenInlineResult) override {}
 
    void onCallbackQuery(const Ptr<CallbackQuery>& callbackQuery) override {}
 
    void onShippingQuery(const Ptr<ShippingQuery>& shippingQuery) override {}
 
    void onPreCheckoutQuery(const Ptr<PreCheckoutQuery>& preCheckoutQuery) override {}
 
    void onPoll(const Ptr<Poll>& poll) override {}
 
    void onPollAnswer(const Ptr<PollAnswer>& pollAnswer) override {}
 
    void onMyChatMember(const Ptr<ChatMemberUpdated>& myChatMemberUpdated) override {}
 
    void onChatMember(const Ptr<ChatMemberUpdated>& chatMemberUpdated) override {}
 
    void onChatJoinRequest(const Ptr<ChatJoinRequest>& chatJoinRequest) override {}
 
    void onChatBoostUpdated(const Ptr<ChatBoostUpdated>& chatBoostUpdated) override {}
 
    void onChatBoostRemoved(const Ptr<ChatBoostRemoved>& chatBoostRemoved) override {}
 
    void onLongPollError(const std::string& errorMessage, ErrorCode errorCode) override {}
};
 
int main() {
  MyBot bot;
  bot.start();
  return 0;
}

</details>

Usage (4 approaches)

1. `FetchContent` (recommended)

Simply use CMake's FetchContent in your project's CMakeLists.txt as below:

cmake_minimum_required(VERSION 3.10)
project(my_bot)
 
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
include(FetchContent)
FetchContent_Declare(tgbotxx
  GIT_REPOSITORY "https://github.com/baderouaich/tgbotxx"
  GIT_TAG main
)
FetchContent_MakeAvailable(tgbotxx)
 
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC tgbotxx)

2. `PkgConfig`: clone and install the library locally, then use PkgConfig:

example

git clone https://github.com/baderouaich/tgbotxx
cd tgbotxx
cmake .. -DCMAKE_BUILD_TYPE=Release
sudo make install 
# On Windows run `make install` as administrator 

cmake_minimum_required(VERSION 3.10)
project(my_bot)
 
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(PkgConfig REQUIRED)
pkg_check_modules(tgbotxx REQUIRED tgbotxx)
 
if (NOT tgbotxx_FOUND)
  message(FATAL_ERROR "Did you install tgbotxx locally?")
endif ()
 
add_executable(${PROJECT_NAME} main.cpp)
target_link_directories(${PROJECT_NAME} PUBLIC ${tgbotxx_LIBRARY_DIRS})
target_include_directories(${PROJECT_NAME} PUBLIC ${tgbotxx_INCLUDE_DIRS})
target_compile_options(${PROJECT_NAME} PUBLIC ${tgbotxx_CFLAGS_OTHER})
target_link_libraries(${PROJECT_NAME} PUBLIC ${tgbotxx_LIBRARIES})

</details>

3. `find_package`: clone and install the library locally, then use find_package(tgbotxx REQUIRED):

example

cmake_minimum_required(VERSION 3.10)
project(my_bot)
 
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(tgbotxx REQUIRED)
 
if (NOT tgbotxx_FOUND)
  message(FATAL_ERROR "Did you install tgbotxx locally?")
endif ()
 
add_executable(${PROJECT_NAME} main.cpp)
target_link_directories(${PROJECT_NAME} PUBLIC ${tgbotxx_LIBRARY_DIRS})
target_include_directories(${PROJECT_NAME} PUBLIC ${tgbotxx_INCLUDE_DIRS})
target_compile_options(${PROJECT_NAME} PUBLIC ${tgbotxx_CFLAGS_OTHER})
target_link_libraries(${PROJECT_NAME} PUBLIC ${tgbotxx_LIBRARIES})

</details>

4. `Submodule`: Use tgbotxx as a project submodule (without installation)

example

You can also use this library as a submodule in your bot project without the need of installing it in your system. Use git clone or git submodule add the library:

git submodule add https://github.com/baderouaich/tgbotxx ./lib/tgbotxx

or

git clone https://github.com/baderouaich/tgbotxx ./lib/tgbotxx

Then add add_subdirectory(lib/tgbotxx) in your CMakeLists.txt.

cmake_minimum_required(VERSION 3.10)
project(my_bot)
 
add_subdirectory(lib/tgbotxx) # <-- clone tgbotxx in your project's lib/ directory
 
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC tgbotxx) # <-- link with tgbotxx

</details>

Other actively maintained Telegram Bot C++ Libraries

tgbot-cpp: C++ library for Telegram bot API
tgbot: C++ library for Telegram Bot API with generated API types and methods

Refs:

Telegram Api Documentation

tgbotxx

CI Status

Examples

Basic sample

Extensive sample

Usage (4 approaches)

1. FetchContent *(recommended)*

2. PkgConfig: clone and install the library locally, then use PkgConfig:

3. find_package: clone and install the library locally, then use find_package(tgbotxx REQUIRED):

4. Submodule: Use tgbotxx as a project submodule (without installation)

Other actively maintained Telegram Bot C++ Libraries

Refs:

1. `FetchContent` (recommended)

2. `PkgConfig`: clone and install the library locally, then use PkgConfig:

3. `find_package`: clone and install the library locally, then use find_package(tgbotxx REQUIRED):

4. `Submodule`: Use tgbotxx as a project submodule (without installation)