代码拉取完成，页面将自动刷新
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 using the async/.await syntax in Rust. It handles all the difficult stuff so you can focus only on your business logic.
123456789:blablabla.TELOXIDE_TOKEN environmental variable to your token:# Unix-like
$ export TELOXIDE_TOKEN=<Your token here>
# Windows command line
$ set TELOXIDE_TOKEN=<Your token here>
# Windows PowerShell
$ $env:TELOXIDE_TOKEN=<Your token here>
# If you're using stable
$ rustup update stable
$ rustup override set stable
# If you're using nightly
$ rustup update nightly
$ rustup override set nightly
cargo new my_bot, enter the directory and put these lines into your Cargo.toml:[dependencies]
teloxide = { version = "0.5", features = ["auto-send", "macros"] }
log = "0.4"
pretty_env_logger = "0.4.0"
tokio = { version = "1.8", features = ["rt-multi-thread", "macros"] }
This bot replies with a dice throw to each received message:
(Full)
use teloxide::prelude::*;
#[tokio::main]
async fn main() {
teloxide::enable_logging!();
log::info!("Starting dices_bot...");
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)
use teloxide::{prelude::*, utils::command::BotCommand};
use std::error::Error;
#[derive(BotCommand)]
#[command(rename = "lowercase", description = "These commands are supported:")]
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<AutoSend<Bot>, Message>,
command: Command,
) -> Result<(), Box<dyn Error + Send + Sync>> {
match command {
Command::Help => cx.answer(Command::descriptions()).await?,
Command::Username(username) => {
cx.answer(format!("Your username is @{}.", username)).await?
}
Command::UsernameAndAge { username, age } => {
cx.answer(format!("Your username is @{} and age is {}.", username, age)).await?
}
};
Ok(())
}
#[tokio::main]
async fn main() {
teloxide::enable_logging!();
log::info!("Starting simple_commands_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)
// Imports are omitted...
#[derive(Transition, From)]
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_bot/src/dialogue/states/start.rs)
// Imports are omitted...
pub struct StartState;
#[teloxide(subtransition)]
async fn start(
_state: StartState,
cx: TransitionIn<AutoSend<Bot>>,
_ans: String,
) -> TransitionOut<Dialogue> {
cx.answer("Let's start! What's your full name?").await?;
next(ReceiveFullNameState)
}
(dialogue_bot/src/dialogue/states/receive_full_name.rs)
// Imports are omitted...
#[derive(Generic)]
pub struct ReceiveFullNameState;
#[teloxide(subtransition)]
async fn receive_full_name(
state: ReceiveFullNameState,
cx: TransitionIn<AutoSend<Bot>>,
ans: String,
) -> TransitionOut<Dialogue> {
cx.answer("How old are you?").await?;
next(ReceiveAgeState::up(state, ans))
}
(dialogue_bot/src/dialogue/states/receive_age.rs)
// Imports are omitted...
#[derive(Generic)]
pub struct ReceiveAgeState {
pub full_name: String,
}
#[teloxide(subtransition)]
async fn receive_age_state(
state: ReceiveAgeState,
cx: TransitionIn<AutoSend<Bot>>,
ans: String,
) -> TransitionOut<Dialogue> {
match ans.parse::<u8>() {
Ok(ans) => {
cx.answer("What's your location?").await?;
next(ReceiveLocationState::up(state, ans))
}
_ => {
cx.answer("Send me a number.").await?;
next(state)
}
}
}
(dialogue_bot/src/dialogue/states/receive_location.rs)
// Imports are omitted...
#[derive(Generic)]
pub struct ReceiveLocationState {
pub full_name: String,
pub age: u8,
}
#[teloxide(subtransition)]
async fn receive_location(
state: ReceiveLocationState,
cx: TransitionIn<AutoSend<Bot>>,
ans: String,
) -> TransitionOut<Dialogue> {
cx.answer(format!("Full name: {}\nAge: {}\nLocation: {}", state.full_name, state.age, ans))
.await?;
exit()
}
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...
#[tokio::main]
async fn main() {
teloxide::enable_logging!();
log::info!("Starting dialogue_bot...");
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 handle_message(
cx: UpdateWithCx<AutoSend<Bot>, Message>,
dialogue: Dialogue,
) -> TransitionOut<Dialogue> {
match cx.update.text().map(ToOwned::to_owned) {
None => {
cx.answer("Send me a text message.").await?;
next(dialogue)
}
Some(ans) => dialogue.react(cx, ans).await,
}
}
#[tokio::main]
async fn main() {
run().await;
}
async fn run() {
// Your logic here...
}
Instead of this:
#[tokio::main]
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:
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.
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手