created_at2020-02-19 17:16:01.057208
updated_at2023-02-15 20:39:59.923612
descriptionAn elegant Telegram bots framework for Rust
size288,479 publish access (github:teloxide:crates-io-publish-access)



v0.11 -> v0.12 migration guide >>


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. 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 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 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.64):
# 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:
teloxide = { version = "0.12", features = ["macros"] }
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 die throw to each received message:


use teloxide::prelude::*;

async fn main() {
    log::info!("Starting throw dice bot...");

    let bot = Bot::from_env();

    teloxide::repl(bot, |bot: Bot, msg: Message| async move {


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};

async fn main() {
    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.")]
    #[command(description = "handle a username.")]
    #[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(, Command::descriptions().to_string()).await?,
        Command::Username(username) => {
            bot.send_message(, format!("Your username is @{username}.")).await?
        Command::UsernameAndAge { username, age } => {
            bot.send_message(, format!("Your username is @{username} and age is {age}."))


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:


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 {
    ReceiveAge {
        full_name: String,
    ReceiveLocation {
        full_name: String,
        age: u8,

async fn main() {
    log::info!("Starting dialogue bot...");

    let bot = Bot::from_env();

            .enter_dialogue::<Message, InMemStorage<State>, State>()
            .branch(dptree::case![State::ReceiveAge { full_name }].endpoint(receive_age))
                dptree::case![State::ReceiveLocation { full_name, age }].endpoint(receive_location),

async fn start(bot: Bot, dialogue: MyDialogue, msg: Message) -> HandlerResult {
    bot.send_message(, "Let's start! What's your full name?").await?;

async fn receive_full_name(bot: Bot, dialogue: MyDialogue, msg: Message) -> HandlerResult {
    match msg.text() {
        Some(text) => {
            bot.send_message(, "How old are you?").await?;
            dialogue.update(State::ReceiveAge { full_name: text.into() }).await?;
        None => {
            bot.send_message(, "Send me plain text.").await?;


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(, "What's your location?").await?;
            dialogue.update(State::ReceiveLocation { full_name, age }).await?;
        _ => {
            bot.send_message(, "Send me a number.").await?;


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(, report).await?;
        None => {
            bot.send_message(, "Send me plain text.").await?;


More examples >>


Q: Where I can ask questions?


  • 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/

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 >>



Commit count: 4249

cargo fmt