Crate teloxide

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. Currently, version 7.0 of Telegram Bot API is supported.

For a high-level overview, see our GitHub repository.

[examples/throw_dice.rs]

use teloxide::prelude::*;

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;

Working with Updates and Messages

There is a great number of update kinds and message kinds to work with! Usually it’s essential to filter specific ones and process them in handler functions. Teloxide provides some filter methods for Update and Message types in UpdateFilterExt and MessageFilterExt traits respectively. In addition to filtering, these methods will inject the appropriate type into your handler functions. For instance, if you use Update::filter_message, the instance of the Message will be available as a parameter for your handler functions. Similarly the use of Message::filter_text will inject a String into the context.

Moreover, filter_map function can inject some dependencies according to the schema flow. More in the example below!

Here is a quick example (filter text message and inject it’s text into the handler function):

use teloxide::{prelude::*, types::User};

pub type Error = Box<dyn std::error::Error + Send + Sync>;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let bot = Bot::from_env();
    let schema = Update::filter_message()
        /*
           Inject the `User` object representing the author of an incoming
           message into every successive handler function (1)
        */
        .filter_map(|update: Update| update.from().cloned())
        .branch(
            /*
               Use filter_text method of MessageFilterExt to accept
               only textual messages. Others will be ignored by this handler (2)
            */
            Message::filter_text().endpoint(process_text_message),
        );

    Dispatcher::builder(bot, schema).build().dispatch().await;
    Ok(())
}

/// Replies to the user's text messages
async fn process_text_message(bot: Bot, user: User, message_text: String) -> Result<(), Error> {
    /*
       The id of a chat with a user is the same as his telegram_id
       from the bot's perspective.

       Injected dependencies:
       - Bot is provided by the Dispatcher::dispatch
       - User is provided by the (1)
       - String is provided by the (2)
    */
    bot.send_message(user.id, format!("Hi! You sent: {message_text}"));
    Ok(())
}

Cargo features

Feature	Description
webhooks	Enables general webhook utilities (almost useless on its own).
webhooks-axum	Enables webhook implementation based on axum framework.
macros	Re-exports macros from teloxide-macros.
ctrlc_handler	Enables the DispatcherBuilder::enable_ctrlc_handler function (enabled by default).
throttle	Enables the Throttle bot adaptor.
cache-me	Enables the CacheMe bot adaptor.
trace-adaptor	Enables the Trace bot adaptor.
erased	Enables the ErasedRequester bot adaptor.
full	Enables all the features except nightly.
nightly	Enables nightly-only features (see the teloxide-core features).
native-tls	Enables the native-tls TLS implementation (enabled by default).
rustls	Enables the rustls TLS implementation.
redis-storage	Enables the Redis storage support for dialogues.
sqlite-storage-nativetls	Enables the Sqlite storage support for dialogues (depends on native-tls).
sqlite-storage-rustls	Enables the Sqlite storage support for dialogues (depends on rustls, conflicts with sqlite-storage-nativetls).
cbor-serializer	Enables the CBOR serializer for dialogues.
bincode-serializer	Enables the Bincode serializer for dialogues.

Re-exports

• pub use repls::repl;
  ctrlc_handler
• pub use repls::repl_with_listener;
  ctrlc_handler
• pub use dispatching::filter_command;
• pub use teloxide_macros as macros;
  macros
• pub use dptree;

Modules

• adaptors
  Wrappers altering functionality of a bot.
• backoff
• dispatching
  An update dispatching model based on dptree.
• error_handlers
  Convenient error handling.
• errors
  Possible error types.
• net
  Network-specific API.
• payloads
  Request data sent to Telegram.
• prelude
  Commonly used items.
• replsctrlc_handler
  REPLs for dispatching updates.
• requests
  Telegram API requests.
• stop
  Stopping asynchronous tasks, e.g., listeners.
• types
  Telegram API types.
• update_listeners
  Receiving updates from Telegram.
• utils
  Some useful utilities.

Macros

• handler
  Filters an enumeration, passing its payload forwards.

Structs

• Bot
  A requests sender.

Enums

• ApiError
  A kind of an API error.
• DownloadError
  An error caused by downloading a file.
• RequestError
  An error caused by sending a request to Telegram.

Functions

• respond
  A shortcut for ResponseResult::Ok(val).