v0.10 -> v0.11 migration guide >>

teloxide

A full-featured framework that empowers you to easily build [Telegram bots](https://telegram.org/blog/bot-revolution) using [Rust](https://www.rust-lang.org/). It handles all the difficult stuff so you can focus only on your business logic.

Highlights

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: ```bash

    Unix-like

$ export TELOXIDE_TOKEN=

Windows command line

$ set TELOXIDE_TOKEN=

Windows PowerShell

$ $env:TELOXIDE_TOKEN= ```

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

    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: toml [dependencies] teloxide = { version = "0.11", features = ["macros", "auto-send"] } log = "0.4" pretty_env_logger = "0.4" tokio = { version = "1.8", features = ["rt-multi-thread", "macros"] }

API overview

The dices bot

This bot replies with a dice throw to each received message:

[[examples/throw_dice.rs](examples/throw_dice.rs)]

```rust,no_run use teloxide::prelude::*;

[tokio::main]

async fn main() { prettyenvlogger::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:

[[examples/command.rs](examples/command.rs)]

```rust,no_run use teloxide::{prelude::*, utils::command::BotCommands};

[tokio::main]

async fn main() { prettyenvlogger::init(); log::info!("Starting command bot...");

let bot = Bot::from_env();

teloxide::commands_repl(bot, answer, Command::ty()).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.sendmessage(msg.chat.id, Command::descriptions().tostring()).await?, Command::Username(username) => { bot.sendmessage(msg.chat.id, format!("Your username is @{username}.")).await? } Command::UsernameAndAge { username, age } => { bot.sendmessage(msg.chat.id, format!("Your username is @{username} and age is {age}.")) .await? } };

Ok(())

} ```

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](examples/dialogue.rs)]

```rust,ignore use teloxide::{dispatching::dialogue::InMemStorage, prelude::*};

type MyDialogue = Dialogue>; type HandlerResult = Result<(), Box>;

[derive(Clone, Default)]

pub enum State { #[default] Start, ReceiveFullName, ReceiveAge { fullname: String, }, ReceiveLocation { fullname: String, age: u8, }, }

[tokio::main]

async fn main() { prettyenvlogger::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 receivefullname(bot: Bot, dialogue: MyDialogue, msg: Message) -> HandlerResult { match msg.text() { Some(text) => { bot.sendmessage(msg.chat.id, "How old are you?").await?; dialogue.update(State::ReceiveAge { fullname: text.into() }).await?; } None => { bot.send_message(msg.chat.id, "Send me plain text.").await?; } }

Ok(())

}

async fn receiveage( bot: Bot, dialogue: MyDialogue, fullname: String, // Available from State::ReceiveAge. msg: Message, ) -> HandlerResult { match msg.text().map(|text| text.parse::()) { Some(Ok(age)) => { bot.sendmessage(msg.chat.id, "What's your location?").await?; dialogue.update(State::ReceiveLocation { fullname, age }).await?; } _ => { bot.send_message(msg.chat.id, "Send me a number.").await?; } }

Ok(())

}

async fn receivelocation( bot: Bot, dialogue: MyDialogue, (fullname, age): (String, u8), // Available from State::ReceiveLocation. msg: Message, ) -> HandlerResult { match msg.text() { Some(location) => { let report = format!("Full name: {fullname}\nAge: {age}\nLocation: {location}"); bot.sendmessage(msg.chat.id, report).await?; dialogue.exit().await?; } None => { bot.send_message(msg.chat.id, "Send me plain text.").await?; } }

Ok(())

} ```

More examples >>

FAQ

Q: Where I can ask questions?

A:

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.

Community bots

Feel free to propose your own bot to our collection!

Show bots using teloxide older than v0.6.0

See 700+ other public repositories using teloxide >>

Contributing

See CONRIBUTING.md.