-green.svg){kind=icon}
A full-featured framework that empowers you to easily build Telegram bots using Rust. It handles all the difficult stuff so you can focus only on your business logic.
- Declarative design.
teloxideis based upondptree, a functional chain of responsibility pattern that allows you to express pipelines of message processing in a highly declarative and extensible style.
-
Feature-rich. You can use both long polling and webhooks, configure an underlying HTTPS client, set a custom URL of a Telegram API server, do graceful shutdown, and much more.
-
Simple dialogues. Our dialogues subsystem is simple and easy-to-use, and, furthermore, is 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 commands. Define bot commands as an
enumand teloxide will parse them automatically β just like JSON structures inserde-jsonand command-line arguments instructopt.
- Download Rust.
- Create a new bot using @Botfather to get a token in the format
123456789:blablabla. - Initialise the
TELOXIDE_TOKENenvironmental 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>- Make sure that your Rust compiler is up to date (
teloxidecurrently requires rustc at least version 1.70):
# If you're using stable
$ rustup update stable
$ rustup override set stable
# If you're using nightly
$ rustup update nightly
$ rustup override set nightly- Run
cargo new my_bot, enter the directory and put these lines into yourCargo.toml:
[dependencies]
teloxide = { version = "0.12", features = ["macros"] }
log = "0.4"
pretty_env_logger = "0.4"
tokio = { version = "1.8", features = ["rt-multi-thread", "macros"] }This bot replies with a dice to each received message:
use teloxide::prelude::*;
#[tokio::main]
async fn main() {
pretty_env_logger::init();
log::info!("Starting throw dice bot...");
let bot = Bot::from_env();
teloxide::repl(bot, |bot: Bot, msg: Message| async move {
bot.send_dice(msg.chat.id).await?;
Ok(())
})
.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
use teloxide::{prelude::*, utils::command::BotCommands};
#[tokio::main]
async fn main() {
pretty_env_logger::init();
log::info!("Starting command bot...");
let bot = Bot::from_env();
Command::repl(bot, answer).await;
}
#[derive(BotCommands, Clone)]
#[command(rename_rule = "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(bot: Bot, msg: Message, cmd: Command) -> ResponseResult<()> {
match cmd {
Command::Help => bot.send_message(msg.chat.id, Command::descriptions().to_string()).await?,
Command::Username(username) => {
bot.send_message(msg.chat.id, format!("Your username is @{username}.")).await?
}
Command::UsernameAndAge { username, age } => {
bot.send_message(msg.chat.id, format!("Your username is @{username} and age is {age}."))
.await?
}
};
Ok(())
}
A dialogue is typically described by an enumeration where each variant is one possible state of the dialogue. There are also state handler functions, which may 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:
use teloxide::{dispatching::dialogue::InMemStorage, prelude::*};
type MyDialogue = Dialogue<State, InMemStorage<State>>;
type HandlerResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
#[derive(Clone, Default)]
pub enum State {
#[default]
Start,
ReceiveFullName,
ReceiveAge {
full_name: String,
},
ReceiveLocation {
full_name: String,
age: u8,
},
}
#[tokio::main]
async fn main() {
pretty_env_logger::init();
log::info!("Starting dialogue bot...");
let bot = Bot::from_env();
Dispatcher::builder(
bot,
Update::filter_message()
.enter_dialogue::<Message, InMemStorage<State>, State>()
.branch(dptree::case![State::Start].endpoint(start))
.branch(dptree::case![State::ReceiveFullName].endpoint(receive_full_name))
.branch(dptree::case![State::ReceiveAge { full_name }].endpoint(receive_age))
.branch(
dptree::case![State::ReceiveLocation { full_name, age }].endpoint(receive_location),
),
)
.dependencies(dptree::deps![InMemStorage::<State>::new()])
.enable_ctrlc_handler()
.build()
.dispatch()
.await;
}
async fn start(bot: Bot, dialogue: MyDialogue, msg: Message) -> HandlerResult {
bot.send_message(msg.chat.id, "Let's start! What's your full name?").await?;
dialogue.update(State::ReceiveFullName).await?;
Ok(())
}
async fn receive_full_name(bot: Bot, dialogue: MyDialogue, msg: Message) -> HandlerResult {
match msg.text() {
Some(text) => {
bot.send_message(msg.chat.id, "How old are you?").await?;
dialogue.update(State::ReceiveAge { full_name: text.into() }).await?;
}
None => {
bot.send_message(msg.chat.id, "Send me plain text.").await?;
}
}
Ok(())
}
async fn receive_age(
bot: Bot,
dialogue: MyDialogue,
full_name: String, // Available from `State::ReceiveAge`.
msg: Message,
) -> HandlerResult {
match msg.text().map(|text| text.parse::<u8>()) {
Some(Ok(age)) => {
bot.send_message(msg.chat.id, "What's your location?").await?;
dialogue.update(State::ReceiveLocation { full_name, age }).await?;
}
_ => {
bot.send_message(msg.chat.id, "Send me a number.").await?;
}
}
Ok(())
}
async fn receive_location(
bot: Bot,
dialogue: MyDialogue,
(full_name, age): (String, u8), // Available from `State::ReceiveLocation`.
msg: Message,
) -> HandlerResult {
match msg.text() {
Some(location) => {
let report = format!("Full name: {full_name}\nAge: {age}\nLocation: {location}");
bot.send_message(msg.chat.id, report).await?;
dialogue.exit().await?;
}
None => {
bot.send_message(msg.chat.id, "Send me plain text.").await?;
}
}
Ok(())
}
- "Migrating my family finance bot from Python to Rust (teloxide) because I am tired of exceptions (part 1)" by Troy KΓΆhler.
- "Migrating my family finance bot from Python to Rust (teloxide) [part 2]" by Troy KΓΆhler.
Q: Where I can ask questions?
A:
- Issues is a good place for well-formed questions about the library design, enhancements, and bug reports.
- GitHub Discussions is a place where you can ask us for help in a less formal manner.
- If you need quick help in real-time, you should ask a question in our official Telegram group.
Q: Do you support the Telegram API for clients?
A: No, only the bots API.
Q: Can I use webhooks?
A: You can! teloxide has a built-in support for webhooks in dispatching::update_listeners::webhooks module. See how it's used in examples/ngrok_ping_pong_bot and examples/heroku_ping_pong_bot.
Q: Can I handle both callback queries and messages within a single dialogue?
A: Yes, see examples/purchase.rs.
Feel free to propose your own bot to our collection!
raine/tgredditβ A bot that sends the top posts of your favorite subreddits to Telegram.magnickolas/remindee-botβ Telegram bot for managing reminders.WaffleLapkin/crate_upd_botβ A bot that notifies about crate updates.mattrighetti/GroupActivityBotβ Telegram bot that keeps track of user activity in groups.alenpaul2001/AurSearchBotβ Telegram bot for searching in Arch User Repository (AUR).ArtHome12/vzmuinebotβ Telegram bot for food menu navigate.studiedlist/EddieBotβ Chatting bot with several entertainment features.modos189/tg_blackbox_botβ Anonymous feedback for your Telegram project.0xNima/spacecraftβ Yet another telegram bot to downloading Twitter spaces.0xNima/Twideoβ Simple Telegram Bot for downloading videos from Twitter via their links.mattrighetti/libgen-bot-rsβ Telegram bot to interface with libgen.zamazan4ik/npaperbot-telegramβ Telegram bot for searching via C++ proposals.studentenherz/dlebotβ A bot to query definitions of words from the Spanish Language Dictionary.fr0staman/fr0staman_botβ Feature rich Telegram game-like bot with pigs π½.franciscofigueira/transferBotβ Telegram bot that notifies of crypto token transfers.
Show bots using `teloxide` older than v0.6.0
mxseev/logramβ Utility that takes logs from anywhere and sends them to Telegram.alexkonovalov/PedigreeBotβ A Telegram bot for building family trees.Hermitter/tepeβ A CLI to command a bot to send messages and files over Telegram.myblackbeard/basketball-betting-botβ The bot lets you bet on NBA games against your buddies.dracarys18/grpmr-rsβ Modular Telegram Group Manager Bot written in Rust.ArtHome12/cognito_botβ The bot is designed to anonymize messages to a group.crapstone/hscttβ A bot that converts HTTP status codes into text.
See 1600+ other public repositories using teloxide >>
See CONRIBUTING.md.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent