Frankenstein
Telegram bot API client for Rust.
It's a complete wrapper for Telegram bot API and it's up to date with version 5.2 of the API.
Frankenstein data structures (rust structs and enums) are mapped one-to-one from Telegram bot API objects and method params. Almost all structs and enums are automatically generated from Telegram Bot API docs with frankestein_creator
Installation
Add this to your Cargo.toml
[dependencies]
frankenstein = "0.3.0"
Usage
Data structures
All objects described in the API docs have direct counterparts in the frankenstein. For example, in the docs there is the user type:
id Integer Unique identifier for this user or bot. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier.
is_bot Boolean True, if this user is a bot
first_name String User's or bot's first name
last_name String Optional. User's or bot's last name
username String Optional. User's or bot's username
language_code String Optional. IETF language tag of the user's language
can_join_groups Boolean Optional. True, if the bot can be invited to groups. Returned only in getMe.
can_read_all_group_messages Boolean Optional. True, if privacy mode is disabled for the bot. Returned only in getMe.
supports_inline_queries Boolean Optional. True, if the bot supports inline queries. Returned only in getMe.
In frankenstein, it's described as:
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct User {
pub id: isize,
pub is_bot: bool,
pub first_name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub last_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub username: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub language_code: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub can_join_groups: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub can_read_all_group_messages: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub supports_inline_queries: Option<bool>,
}
Optional fields are described as Option enum.
Every struct has the new method which used for initialization. It accepts only required fields, optional fields are set to None:
pub fn new(id: isize, is_bot: bool, first_name: String) -> User {
Self {
id,
is_bot,
first_name,
last_name: None,
username: None,
language_code: None,
can_join_groups: None,
can_read_all_group_messages: None,
supports_inline_queries: None,
}
}
All fields have setter and getter methods :
...
pub fn set_supports_inline_queries(&mut self, supports_inline_queries: Option<bool>) {
self.supports_inline_queries = supports_inline_queries;
}
pub fn id(&self) -> isize {
self.id
}
...
For method parameters, the same approach is used. The only difference for parameters is the name of the struct in frankenstein ends with Params postfix.
For example, parameters for leaveChat method:
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct LeaveChatParams {
chat_id: ChatIdEnum,
}
Making requests
To make a request to the telegram bot api:
- Initialize the
Apistruct:
use frankenstein::Api;
use frankenstein::TelegramApi;
...
let token = "My_token".to_string()
let api = Api::new(token);
- Use this api object to make requests to the Bot API:
let mut update_params = GetUpdatesParams::new();
update_params.set_allowed_updates(Some(vec!["message".to_string()]));
let result = api.get_updates(&update_params);
Every function returns a Result enum with a successful response or failed response.
See a complete example in the examples directory.
Uploading files
Some methods in the API allow uploading files. In the frankenstein for this FileEnum struct is used:
pub enum FileEnum {
InputFileVariant(InputFile),
StringVariant(String),
}
pub struct InputFile {
path: std::path::PathBuf
}
It has two variants:
FileEnum::StringVariantis used to pass id of the already uploaded fileFileEnum::InputFileVariantis 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 docs.rs
Replacing the default http client
The library uses ureq http client by default, but it can be easily replaced with any http client of your choice:
ureqcomes with a default feature (impl). So the feature should be disabled:
frankenstein = { version = "0.3", default-features = false }
- Implement
TelegramApitrait which requires two functions:
request_with_form_datais used to upload filesrequestis used for requests without file uploads
You can check the default TelegramApi trait implementation for ureq.
Also, you can take a look at the implementation for isahc http client in the examples directory.
Without the default ureq implementation, frankenstein has only two dependencies - serde and serde_json.
Contributing
- Fork it!
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Author
Ayrat Badykov (@ayrat555)
218 Dec 27, 2022
249 Oct 18, 2022
216 Dec 25, 2022
3 Jul 14, 2022
5 Mar 30, 2023
338 Jan 1, 2023
35 Jun 26, 2022
138 Dec 27, 2022
548 Dec 31, 2022
7 Jun 15, 2022
29 Nov 24, 2022
44 Oct 13, 2022
617 Dec 27, 2022
3 Sep 18, 2021
7 Aug 4, 2022
2 Dec 14, 2022
4 Jan 4, 2020
20 Jul 17, 2021