v0.4.0 => v0.5.0 migration guide >>
){kind=icon}
-green.svg){kind=icon}
A full-featured framework that empowers you to easily build [Telegram bots](https://telegram.org/blog/bot-revolution) using the [`async`/`.await`](https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html) syntax in [Rust](https://www.rust-lang.org/). It handles all the difficult stuff so you can focus only on your business logic.
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].
123456789:blablabla.TELOXIDE_TOKEN environmental variable to your token:
```bash
$ export TELOXIDE_TOKEN=
$ set TELOXIDE_TOKEN=
4. Make sure that your Rust compiler is up to date:
bash
$ rustup update stable $ rustup override set stable
$ rustup update nightly $ rustup override set nightly ```
cargo new my_bot, enter the directory and put these lines into your Cargo.toml:
toml
[dependencies]
teloxide = { version = "0.4", features = ["auto-send", "macros"] }
log = "0.4.8"
pretty_env_logger = "0.4.0"
tokio = { version = "1.3", features = ["rt-multi-thread", "macros"] }
This bot replies with a dice throw to each received message:
(Full) ```rust,no_run use teloxide::prelude::*;
async fn main() { teloxide::enablelogging!(); log::info!("Starting dicesbot...");
let bot = Bot::from_env().auto_send();
teloxide::repl(bot, |message| async move {
message.answer_dice().await?;
respond(())
})
.await;
} ```
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) ```rust,no_run use teloxide::{prelude::*, utils::command::BotCommand};
use std::error::Error;
enum Command { #[command(description = "display this text.")] Help, #[command(description = "handle a username.")] Username(String), #[command(description = "handle a username and an age.", parse_with = "split")] UsernameAndAge { username: String, age: u8 }, }
async fn answer(
cx: UpdateWithCx
Ok(())
}
async fn main() { teloxide::enablelogging!(); log::info!("Starting simplecommands_bot...");
let bot = Bot::from_env().auto_send();
let bot_name: String = panic!("Your bot's name here");
teloxide::commands_repl(bot, bot_name, answer).await;
} ```
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) ```rust,ignore // Imports are omitted...
pub enum Dialogue { Start(StartState), ReceiveFullName(ReceiveFullNameState), ReceiveAge(ReceiveAgeState), ReceiveLocation(ReceiveLocationState), }
impl Default for Dialogue { fn default() -> Self { Self::Start(StartState) } } ```
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::Start
(dialogue_bot/src/dialogue/states/start.rs) ```rust,ignore // Imports are omitted...
pub struct StartState;
async fn start(
_state: StartState,
cx: TransitionIn
Dialogue::ReceiveFullName
(dialoguebot/src/dialogue/states/receivefull_name.rs) ```rust,ignore // Imports are omitted...
pub struct ReceiveFullNameState;
async fn receivefullname(
state: ReceiveFullNameState,
cx: TransitionIn
Dialogue::ReceiveAge
(dialoguebot/src/dialogue/states/receiveage.rs) ```rust,ignore // Imports are omitted...
pub struct ReceiveAgeState { pub full_name: String, }
async fn receiveagestate(
state: ReceiveAgeState,
cx: TransitionIn
Dialogue::ReceiveLocation
(dialoguebot/src/dialogue/states/receivelocation.rs) ```rust,ignore // Imports are omitted...
pub struct ReceiveLocationState { pub full_name: String, pub age: u8, }
async fn receivelocation(
state: ReceiveLocationState,
cx: TransitionIn
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:
(dialogue_bot/src/main.rs) ```rust,ignore // Imports are omitted...
async fn main() { teloxide::enablelogging!(); log::info!("Starting dialoguebot...");
let bot = Bot::from_env().auto_send();
teloxide::dialogues_repl(bot, |message, dialogue| async move {
handle_message(message, dialogue).await.expect("Something wrong with the bot!")
})
.await;
}
async fn handlemessage(
cx: UpdateWithCx
Use this pattern:
```rust
async fn main() { run().await; }
async fn run() { // Your logic here... } ```
Instead of this:
```rust
async fn main() { // Your logic here... } ```
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.
Q: Where I can ask questions?
A: Issues is a good place for well-formed questions, for example, about:
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: - Marvin's Marvellous Guide to All Things Webhook - Using self-signed certificates
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.
Feel free to propose your own bot to our collection!
:help for Vim in Telegram.See CONRIBUTING.md.