frankenstein

Frankenstein

Telegram bot API client for Rust.

It's a complete wrapper for Telegram bot API, and it's up-to-date with version 10.3 of the API.

Frankenstein's data structures (Rust structs and enums) are mapped one-to-one from Telegram bot API types and method parameters.

Installation

Run cargo add frankenstein or add the following to your Cargo.toml.

[dependencies]
frankenstein = { version = "0.52", features = [] }

You likely want to use either a blocking or an async client. Enable it via the Features.

Features

Without enabling any additional features this crate will only ship with Telegram types.

• blocking (synchronous)
  • client-ureq - a blocking HTTP API client based on ureq
  • trait-sync - a blocking API trait, it's included in the client-ureq feature. It may be useful for people who want to create a custom blocking client (for example, replacing an HTTP client)
• async
  • client-reqwest - an async HTTP API client based on reqwest. This client partially supports wasm32, but file uploads are currently not supported there.
  • trait-async - an async API trait, it's used in the client-reqwest. It may be useful for people who want to create a custom async client

For example for the async client add the following line to your Cargo.toml file:

frankenstein = { version = "0.52", features = ["client-reqwest"] }

Usage

Examples in this section use the blocking client (frankenstein::Api), but async examples would look the same (just replace frankenstein::Api with frankenstein::AsyncApi)

Data structures

All types described in the API docs have direct counterparts in the Frankenstein. For example, in the docs there is the user type:

…

In Frankenstein, it's described like this:

pub struct User {
    pub id: u64,
    pub is_bot: bool,
    pub first_name: String,
    pub last_name: Option,
    pub username: Option,
    pub language_code: Option,
    pub can_join_groups: Option,
    pub can_read_all_group_messages: Option,
    pub supports_inline_queries: Option,
}

Optional fields are described as Option.

Every struct can be created with the associated builder. Only required fields are required to set, optional fields are set to None when not provided:

use frankenstein::methods::SendMessageParams;
let send_message_params = SendMessageParams::builder()
    .chat_id(1337)
    .text("hello")
    .build();

Making requests

…

Every function returns a Result with a successful response or failed response.

See more examples in the examples directory.

Uploading files

Some methods in the API allow uploading files. In the Frankenstein for this FileUpload enum is used:

pub enum FileUpload {
    InputFile(InputFile),
    String(String),
}

pub struct InputFile {
    path: std::path::PathBuf
}

It has two variants:

• FileUpload::String is used to pass the ID of the already uploaded file
• FileUpload::InputFile is used to upload a new file using multipart upload.

Documentation

Frankenstein implements all Telegram bot API methods. To see which parameters you should pass, check the official Telegram Bot API documentation or docs.rs/frankenstein

You can check out real-world bots created using this library:

• El Monitorro - RSS/Atom/JSON feed reader.
• subvt-telegram-bot - A Telegram bot for the validators of the Polkadot and Kusama.
• wdr-maus-downloader - checks for a new episode of the WDR Maus and downloads it.
• weather_bot_rust - A Telegram bot that provides weather info around the world.

Contributing

1. Fork it!
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Author

Ayrat Badykov (@ayrat555)