Crate teloxide

Expand description

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.5 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 dispatching::filter_mention_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.
sugar: Some syntax sugar support for TBA functionality.
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).

Crate teloxideCopy item path