teloxide

Highlights

• Declarative design. teloxide is based upon dptree, 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 simply replace one line to achieve persistence. Out-of-the-box storages include Redis and Sqlite.

• Strongly typed commands. Define bot commands as an enum and teloxide will parse them automatically — just like JSON structures in serde-json and command-line arguments in structopt.

Setting up your environment

1. Download Rust.
2. Create a new bot using @Botfather to get a token in the format 123456789:blablabla.
3. Initialise the 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>

1. Make sure that your Rust compiler is up to date (teloxide currently requires rustc at least version 1.85):

# If you're using stable
$ rustup update stable
$ rustup override set stable

# If you're using nightly
$ rustup update nightly
$ rustup override set nightly

1. Run cargo new my_bot, enter the directory and put these lines into your Cargo.toml:

[dependencies]
teloxide = { version = "0.17.0", features = ["macros"] }
log = "0.4"
pretty_env_logger = "0.5"
tokio = { version =  "1.39", features = ["rt-multi-thread", "macros"] }

Note: if there is functionality in master that is not released yet, you can pull the Git repository as follows:

teloxide = { git = "https://github.com/teloxide/teloxide.git", features = ["macros"] }

API overview

The dices bot

This bot replies with a dice to each received message:

[examples/throw_dice.rs]

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

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

[examples/command.rs]

…

Dialogues management

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:

[examples/dialogue.rs]

…

More examples >>

Testing

The community has made a crate called teloxide_tests for testing teloxide bots.

See some testing examples >>

Tutorials

• dptree starter guide with teloxide
• "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.

FAQ

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.rs and examples/heroku_ping_pong_bot.rs.

Q: Can I handle both callback queries and messages within a single dialogue?

A: Yes, see examples/purchase.rs.

Q: How can I organize complex logic?

A: You can use CommonVoiceBot as an example of a bot with a nested dialogue structure distributed across different files.

Q: Where can I find a WebApp example?

A: Check out @TheAwiteb's WebApp teloxide example.

Community bots

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.

See 2500+ other public repositories using teloxide >>

Contributing

See CONRIBUTING.md.