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.
Table of contents
- Highlights
- Setting up your environment
- API overview
- Recommendations
- Cargo features
- FAQ
- Community bots
- Contributing
Highlights
- Functional reactive design. teloxide has functional reactive design, allowing you to declaratively manipulate streams of updates from Telegram using filters, maps, folds, zips, and a lot of other adaptors.
- Persistence. Dialogues management is independent of how/where dialogues are stored: you can just replace one line and make them persistent. Out-of-the-box storages include Redis.
- Strongly typed bot commands. You can describe bot commands as enumerations, and then they'll be automatically constructed from strings. Just like you describe 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
- Be sure that you are up to date:
# If you're using stable
# If you're using nightly
- Execute
cargo new my_bot
, enter the directory and put these lines into yourCargo.toml
:
[]
= "0.3"
= "0.3"
= "0.4.8"
= "0.4.0"
= { = "0.2.11", = ["rt-threaded", "macros"] }
API overview
The dices bot
This bot throws a dice on each incoming 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)
// Imports are omitted...
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 a FSM.
Below is a bot, which 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 yet exist, Dialogue::default()
is invoked, which is Dialogue::Start
. 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 subtransitions 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 because of the #[tokio::main]
macro. However, the examples in this README use the second variant for brevity.
Cargo features
redis-storage
-- enables the Redis support.cbor-serializer
-- enables the CBOR serializer for dialogues.bincode-serializer
-- enables the Bincode serializer for dialogues.frunk
-- enablesteloxide::utils::UpState
, which allows mapping from a structure offield1, ..., fieldN
to a structure offield1, ..., fieldN, fieldN+1
.
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 enough good ecosystem and the language itself to be suitable for writing bots.
UPD: The current design spreads 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. What is even more interesting is that mux-stream could make a library from teloxide, not a framework, since the design 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 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 push your own bot into our collection!
- Rust subreddit reader
- vzmuinebot -- Telegram bot for food menu navigate
- Tepe -- A CLI to command a bot to send messages and files over Telegram
Contributing
See CONRIBUTING.md.