Ctrl+K
Ctrl+K

Versions

Quick Start

Quick Start#

Note

banana is not a Telegram Bot Framework but a generic statically typed and highly-configurable thin wrapper over Telegram Bot API.

banana was designed to be both minimalistic and comprehensive at the same time. It doesn’t provide high-level abstractions or even TelegramBot class. Its main goal is to allow developer to build necessary abstractions on top of the banana API, abstracting from the Telegram API implementation.

You’ve been warned!

There is still only one way to add banana to your project – as a CMake subdirectory.

Adding as a CMake subdirectory#

First of all you need to add banana as a subdirectory to your CMakeLists:

# Assuming banana is cloned to project-dir/external/banana
add_subdirectory(external/banana)

That’s it. Now you can link banana target to your app:

target_link_libraries(your-project-name PRIVATE banana)

#include <banana/types.hpp> // Telegram API types
#include <banana/api.hpp> // Telegram API methods
// etc..

However, you also need a connector to make API requests.

Choosing a connector#

Let’s start with the simplest blocking connector.

Windows#

WinAPI-connector is the only dependency-free connector. It’s built on top of WinAPI, so it doesn’t require any additional libraries to make https requests.

target_link_libraries(your-project-name PRIVATE banana-winapi) # banana-winapi includes banana

#include <banana/connector/winapi.hpp>

banana::connector::winapi_blocking connector("<TG_BOT_TOKEN>");

Linux/macOS#

cpr-based connector is the best choice for non-windows OS. It depends on cpr, which in turn requires OpenSSL.

target_link_libraries(your-project-name PRIVATE banana-cpr) # banana-cpr includes banana

You also should do any of:

  • Manually add and link cpr library to your project

  • Pass -DBANANA_USE_BUNDLED_CPR=ON to CMake (automatically download cpr using FetchContent and link it to banana-cpr)

#include <banana/connector/cpr.hpp>

banana::connector::cpr_blocking connector("<TG_BOT_TOKEN>");

“Default” connector#

To choose connector in a truly cross-platform way, you can use default connector (if you don’t want to link OpenSSL for cpr on Windows and hate boost-based connector). There is an additional CMake target banana-default that provides header #include <banana/connector/default.hpp> and default_blocking_monadic and default_blocking connectors:

On Windows:

  • using default_blocking = winapi_blocking;

  • using default_blocking_monadic = winapi_blocking_monadic;

  • CMake target: banana-default = banana-winapi

Otherwise:

  • using default_blocking = cpr_blocking;

  • using default_blocking_monadic = cpr_blocking_monadic;

  • CMake target: banana-default = banana-cpr

Hello, world!#

The following piece of code shows how to send simple "Hello, world!" message. We use “default” connector as an example.

#include <banana/connector/default.hpp>
#include <banana/api.hpp>

#include <iostream>

int main() {
    banana::connector::default_blocking connector("<TG_BOT_TOKEN>");

    banana::api::message_t message = banana::api::send_message(connector, { "@username", "Hello, world!" });
    // since C++20: banana::api::send_message(connector, { .chat_id = "@username", .text = "Hello, world!" });

    std::cout << "message sent: " << message.message_id;
}

Line-by-line explanation#

banana::connector::default_blocking connector("<TG_BOT_TOKEN>");

Create default_blocking connector that returns T from any API request or throws an exception in case of error. If you don’t like exceptions, try default_blocking_monadic instead.

banana::api::message_t message = banana::api::send_message(connector, { "@username", "Hello, world!" });

Make blocking request and get the result (see banana::api::send_message() for details)

std::cout << "message sent: " << message.message_id;

Print message id. That’s all ✨

Contents