v0.4.0 => v0.5.0 migration guide >>
A full-featured framework that empowers you to easily build Telegram bots using the async
/.await
syntax in Rust. It handles all the difficult stuff so you can focus only on your business logic.
Highlights
- Functional reactive design. teloxide follows functional reactive design, allowing you to declaratively manipulate streams of updates from Telegram using filters, maps, folds, zips, and a lot of other adaptors.
- Dialogues management subsystem. We have designed our dialogues management subsystem to be easy-to-use, and, furthermore, to be agnostic of how/where dialogues are stored. For example, you can just replace a one line to achieve persistence. Out-of-the-box storages include Redis and Sqlite.
- Strongly typed bot commands. You can describe bot commands as enumerations, and then they'll be automatically constructed from strings — just like JSON structures in serde-json and command-line arguments in structopt.
Setting up your environment
- Download Rust.
- Create a new bot using @Botfather to get a token in the format
123456789:blablabla
. - Initialise the
TELOXIDE_TOKEN
environmental variable to your token:
# Unix-like
# Windows
- Make sure that your Rust compiler is up to date:
# If you're using stable
# If you're using nightly
- Run
cargo new my_bot
, enter the directory and put these lines into yourCargo.toml
:
[]
= { = "0.4", = ["auto-send", "macros"] }
= "0.4.8"
= "0.4.0"
= { = "1.3", = ["rt-multi-thread", "macros"] }
API overview
The dices bot
This bot replies with a dice throw to each received message:
(Full)
use *;
async
Commands
Commands are strongly typed and defined declaratively, similar to how we define CLI using structopt and JSON structures in serde-json. The following bot accepts these commands:
/username <your username>
/usernameandage <your username> <your age>
/help
(Full)
use ;
use Error;
async
async
Dialogues management
A dialogue is described by an enumeration where each variant is one of possible dialogue's states. There are also subtransition functions, which turn a dialogue from one state to another, thereby forming an FSM.
Below is a bot that asks you three questions and then sends the answers back to you. First, let's start with an enumeration (a collection of our dialogue's states):
(dialogue_bot/src/dialogue/mod.rs)
// Imports are omitted...
When a user sends a message to our bot and such a dialogue does not exist yet, a Dialogue::default()
is invoked, which is a Dialogue::Start
in this case. Every time a message is received, an associated dialogue is extracted and then passed to a corresponding subtransition function:
(dialogue_bot/src/dialogue/states/start.rs)
// Imports are omitted...
;
async
(dialogue_bot/src/dialogue/states/receive_full_name.rs)
// Imports are omitted...
;
async
(dialogue_bot/src/dialogue/states/receive_age.rs)
// Imports are omitted...
async
(dialogue_bot/src/dialogue/states/receive_location.rs)
// Imports are omitted...
async
All these subtransition functions accept a corresponding state (one of the many variants of Dialogue
), a context, and a textual message. They return TransitionOut<Dialogue>
, e.g. a mapping from <your state type>
to Dialogue
.
Finally, the main
function looks like this:
// Imports are omitted...
async
async
Recommendations
- Use this pattern:
async
async
Instead of this:
async
The second one produces very strange compiler messages due to the #[tokio::main]
macro. However, the examples in this README use the second variant for brevity.
FAQ
Q: Where I can ask questions?
A: Issues is a good place for well-formed questions, for example, about:
- the library design;
- enhancements;
- bug reports;
- ...
If you can't compile your bot due to compilation errors and need quick help, feel free to ask in our official Telegram group.
Q: Do you support the Telegram API for clients?
A: No, only the bots API.
Q: Why Rust?
A: Most programming languages have their own implementations of Telegram bots frameworks, so why not Rust? We think Rust provides a good enough ecosystem and the language for it to be suitable for writing bots.
UPD: The current design relies on wide and deep trait bounds, thereby increasing cognitive complexity. It can be avoided using mux-stream, but currently the stable Rust channel doesn't support necessary features to use mux-stream conveniently. Furthermore, the mux-stream could help to make a library out of teloxide, not a framework, since the design in this case could be defined by just combining streams of updates.
Q: Can I use webhooks?
A: teloxide doesn't provide special API for working with webhooks due to their nature with lots of subtle settings. Instead, you should setup your webhook by yourself, as shown in examples/ngrok_ping_pong_bot
and examples/heroku_ping_pong_bot
.
Associated links:
Q: Can I use different loggers?
A: Yes. You can setup any logger, for example, fern, e.g. teloxide has no specific requirements as it depends only on log. Remember that enable_logging!
and enable_logging_with_filter!
are just optional utilities.
Community bots
Feel free to propose your own bot to our collection!
- WaffleLapkin/crate_upd_bot -- A bot that notifies about crate updates.
- dracarys18/grpmr-rs -- A telegram group manager bot with variety of extra features.
- steadylearner/subreddit_reader -- A bot that shows the latest posts at Rust subreddit.
- ArtHome12/vzmuinebot -- Telegram bot for food menu navigate.
- ArtHome12/cognito_bot -- The bot is designed to anonymize messages to a group.
- Hermitter/tepe -- A CLI to command a bot to send messages and files over Telegram.
- pro-vim/tg-vimhelpbot -- Link
:help
for Vim in Telegram. - sschiz/janitor-bot -- A bot that removes users trying to join to a chat that is designed for comments.
- myblackbeard/basketball-betting-bot -- The bot lets you bet on NBA games against your buddies.
- slondr/BeerHolderBot -- A bot that holds your beer.
- mxseev/logram -- Utility that takes logs from anywhere and sends them to Telegram.
- msfjarvis/walls-bot-rs -- Telegram bot for my wallpapers collection, in Rust.
- MustafaSalih1993/Miss-Vodka-Telegram-Bot -- A telegram bot written in rust using "Teloxide" library.
- x13a/tg-prompt -- Telegram prompt.
- magnickolas/remindee-bot -- Telegram bot for managing reminders.
- cyberknight777/knight-bot -- A telegram bot with variety of fun features.
Contributing
See CONRIBUTING.md.