teloxide

A full-featured framework that empowers you to easily build [Telegram bots](https://telegram.org/blog/bot-revolution) using the [`async`/`.await`](https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html) syntax in [Rust](https://www.rust-lang.org/). It handles all the difficult stuff so you can focus only on your business logic.

Highlights

Functional reactive design. teloxide has [functional reactive design], allowing you to declaratively manipulate streams of updates from Telegram using filters, maps, folds, zips, and a lot of [other adaptors].
Persistence. Dialogues management is independent of how/where dialogues are stored: you can just replace one line and make them [persistent]. Out-of-the-box storages include [Redis].
Strongly typed bot commands. You can describe bot commands as enumerations, and then they'll be automatically constructed from strings. Just like you describe JSON structures in [serde-json] and command-line arguments in [structopt].

Setting up your environment

Download Rust.
Create a new bot using @Botfather to get a token in the format 123456789:blablabla.
Initialise the TELOXIDE_TOKEN environmental variable to your token: ```bash
Unix-like

$ export TELOXIDE_TOKEN=

Windows

$ set TELOXIDE_TOKEN= 4. Be sure that you are up to date: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 ```

Execute cargo new my_bot, enter the directory and put these lines into your Cargo.toml: ```toml [dependencies] teloxide = "0.3.0" teloxide-macros = "0.3.2"

log = "0.4.8" prettyenvlogger = "0.4.0"

tokio = { version = "0.2.11", features = ["rt-threaded", "macros"] } ```

API overview

The dices bot

This bot throws a dice on each incoming message:

(Full) ```rust use teloxide::prelude::*;

[tokio::main]

async fn main() { teloxide::enablelogging!(); log::info!("Starting dicesbot...");

let bot = Bot::from_env();

teloxide::repl(bot, |message| async move {
    message.answer_dice().send().await?;
    ResponseResult::<()>::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

(Full) ```rust // Imports are omitted...

[derive(BotCommand)]

[command(rename = "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(cx: UpdateWithCx, command: Command) -> ResponseResult<()> { match command { Command::Help => cx.answer(Command::descriptions()).send().await?, Command::Username(username) => { cx.answerstr(format!("Your username is @{}.", username)).await? } Command::UsernameAndAge { username, age } => { cx.answerstr(format!("Your username is @{} and age is {}.", username, age)).await? } };

Ok(())

}

[tokio::main]

async fn main() { teloxide::enablelogging!(); log::info!("Starting simplecommands_bot...");

let bot = Bot::from_env();

teloxide::commands_repl(bot, panic!("Your bot's name here"), answer).await;

} ```

Dialogues management

A dialogue is described by an enumeration, where each variant is one of possible dialogue's states. There are also subtransition functions, which turn a dialogue from one state to another, thereby forming a [FSM].

Below is a bot, which asks you three questions and then sends the answers back to you. First, let's start with an enumeration (a collection of our dialogue's states):

(dialogue_bot/src/dialogue/mod.rs) ```rust // Imports are omitted...

[derive(Transition, From)]

pub enum Dialogue { Start(StartState), ReceiveFullName(ReceiveFullNameState), ReceiveAge(ReceiveAgeState), ReceiveLocation(ReceiveLocationState), }

impl Default for Dialogue { fn default() -> Self { Self::Start(StartState) } } ```

When a user sends a message to our bot, and such a dialogue does not yet exist, Dialogue::default() is invoked, which is Dialogue::Start. Every time a message is received, an associated dialogue is extracted, and then passed to a corresponding subtransition function:

Dialogue::Start

(dialogue_bot/src/dialogue/states/start.rs) ```rust // Imports are omitted...

pub struct StartState;

[teloxide(subtransition)]

async fn start(state: StartState, cx: TransitionIn, _ans: String) -> TransitionOut { cx.answerstr("Let's start! What's your full name?").await?; next(ReceiveFullNameState) } ```

Dialogue::ReceiveFullName

(dialoguebot/src/dialogue/states/receivefull_name.rs) ```rust // Imports are omitted...

[derive(Generic)]

pub struct ReceiveFullNameState;

[teloxide(subtransition)]

async fn receivefullname( state: ReceiveFullNameState, cx: TransitionIn, ans: String, ) -> TransitionOut { cx.answer_str("How old are you?").await?; next(ReceiveAgeState::up(state, ans)) } ```

Dialogue::ReceiveAge

(dialoguebot/src/dialogue/states/receiveage.rs) ```rust // Imports are omitted...

[derive(Generic)]

pub struct ReceiveAgeState { pub full_name: String, }

[teloxide(subtransition)]

async fn receiveagestate( state: ReceiveAgeState, cx: TransitionIn, ans: String, ) -> TransitionOut { match ans.parse::() { Ok(ans) => { cx.answerstr("What's your location?").await?; next(ReceiveLocationState::up(state, ans)) } _ => { cx.answerstr("Send me a number.").await?; next(state) } } } ```

Dialogue::ReceiveLocation

(dialoguebot/src/dialogue/states/receivelocation.rs) ```rust // Imports are omitted...

[derive(Generic)]

pub struct ReceiveLocationState { pub full_name: String, pub age: u8, }

[teloxide(subtransition)]

async fn receivelocation( state: ReceiveLocationState, cx: TransitionIn, ans: String, ) -> TransitionOut { cx.answerstr(format!("Full name: {}\nAge: {}\nLocation: {}", state.full_name, state.age, ans)) .await?; exit() } ```

All these subtransitions accept a corresponding state (one of the many variants of Dialogue), a context, and a textual message. They return TransitionOut<Dialogue>, e.g. a mapping from <your state type> to Dialogue.

Finally, the main function looks like this:

(dialogue_bot/src/main.rs) ```rust // Imports are omitted...

[tokio::main]

async fn main() { teloxide::enablelogging!(); log::info!("Starting dialoguebot...");

let bot = Bot::from_env();

teloxide::dialogues_repl(bot, |message, dialogue| async move {
    handle_message(message, dialogue).await.expect("Something wrong with the bot!")
})
.await;

}

async fn handlemessage(cx: UpdateWithCx, dialogue: Dialogue) -> TransitionOut { match cx.update.textowned() { None => { cx.answer_str("Send me a text message.").await?; next(dialogue) } Some(ans) => dialogue.react(cx, ans).await, } } ```

More examples!

Recommendations

Use this pattern:

```rust

[tokio::main]

async fn main() { run().await; }

async fn run() { // Your logic here... } ```

Instead of this:

```rust

[tokio::main]

async fn main() { // Your logic here... } ```

The second one produces very strange compiler messages because of the #[tokio::main] macro. However, the examples in this README use the second variant for brevity.

Cargo features

redis-storage -- enables the [Redis] support.
cbor-serializer -- enables the [CBOR] serializer for dialogues.
bincode-serializer -- enables the [Bincode] serializer for dialogues.
frunk -- enables [teloxide::utils::UpState], which allows mapping from a structure of field1, ..., fieldN to a structure of field1, ..., fieldN, fieldN+1.

FAQ

Q: Where I can ask questions?

A: Issues is a good place for well-formed questions, for example, about:

the library design;
enhancements;
bug reports;
...

If you can't compile your bot due to compilation errors and need quick help, feel free to ask in our official Telegram group.

Q: Do you support the Telegram API for clients?

A: No, only the bots API.

Q: Why Rust?

A: Most programming languages have their own implementations of Telegram bots frameworks, so why not Rust? We think Rust provides enough good ecosystem and the language itself to be suitable for writing bots.

UPD: The current design spreads wide and deep trait bounds, thereby increasing cognitive complexity. It can be avoided using [mux-stream], but currently the stable Rust channel doesn't support necessary features to use [mux-stream] conveniently. What is even more interesting is that [mux-stream] could make a library from teloxide, not a framework, since the design could be defined by just combining streams of updates.

Q: Can I use webhooks?

A: teloxide doesn't provide special API for working with webhooks due to their nature with lots of subtle settings. Instead, you setup your webhook by yourself, as shown in examples/ngrok_ping_pong_bot and examples/heroku_ping_pong_bot.

Associated links: - Marvin's Marvellous Guide to All Things Webhook - Using self-signed certificates

Q: Can I use different loggers?

A: Yes. You can setup any logger, for example, [fern], e.g. teloxide has no specific requirements as it depends only on [log]. Remember that [enable_logging!] and [enable_logging_with_filter!] are just optional utilities.

Community bots

Feel free to push your own bot into our collection!

Contributing

See CONRIBUTING.md.

teloxide

Table of contents

Highlights

Setting up your environment

Unix-like

Windows

If you're using stable

If you're using nightly

API overview

The dices bot

[tokio::main]

Commands

[derive(BotCommand)]

[command(rename = "lowercase", description = "These commands are supported:")]

[tokio::main]

Dialogues management

[derive(Transition, From)]

[teloxide(subtransition)]

[derive(Generic)]

[teloxide(subtransition)]

[derive(Generic)]

[teloxide(subtransition)]

[derive(Generic)]

[teloxide(subtransition)]

[tokio::main]

Recommendations

[tokio::main]

[tokio::main]

Cargo features

FAQ

Community bots

Contributing