Highlights

• 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 simply replace 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:

4. Make sure that your Rust compiler is up to date (
   teloxide
   currently requires rustc at least version 1.82):

5. Run
   cargo new my_bot
   , enter the directory and put these lines into your
   Cargo.toml
   :

Note: if there is functionality in master that is not released yet, you can pull the Git repository as follows:

API overview

The dices bot

This bot replies with a dice to each received message:

[

]

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

[

]

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:

[

]

More examples >>

Testing

The community has made a crate called

for testing

teloxide

bots.

See some testing examples >>

Tutorials

• dptree
  starter guide with teloxide
• "Migrating my family finance bot from Python to Rust (teloxide) because I am tired of exceptions (part 1)" by Troy Köhler.
• "Migrating my family finance bot from Python to Rust (teloxide) [part 2]" by Troy Köhler.

FAQ

Q: Where I can ask questions?

A:

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

has a built-in support for webhooks in

dispatching::update_listeners::webhooks

module. See how it's used in

examples/ngrok_ping_pong_bot.rs

and

examples/heroku_ping_pong_bot.rs

.

Q: Can I handle both callback queries and messages within a single dialogue?

A: Yes, see

.

Q: How can I organize complex logic?

A: You can use

as an example of a bot with a nested dialogue structure distributed across different files.

Q: Where can I find a WebApp example?

A: Check out @TheAwiteb's WebApp

example.

Community bots

Feel free to propose your own bot to our collection!

• raine/tgreddit
  — A bot that sends the top posts of your favorite subreddits to Telegram.
• magnickolas/remindee-bot
  — Telegram bot for managing reminders.
• WaffleLapkin/crate_upd_bot
  — A bot that notifies about crate updates.
• mattrighetti/GroupActivityBot
  — Telegram bot that keeps track of user activity in groups.
• alenpaul2001/AurSearchBot
  — Telegram bot for searching in Arch User Repository (AUR).
• ArtHome12/vzmuinebot
  — Telegram bot for food menu navigate.
• studiedlist/EddieBot
  — Chatting bot with several entertainment features.
• modos189/tg_blackbox_bot
  — Anonymous feedback for your Telegram project.
• 0xNima/spacecraft
  — Yet another telegram bot to downloading Twitter spaces.
• 0xNima/Twideo
  — Simple Telegram Bot for downloading videos from Twitter via their links.
• mattrighetti/libgen-bot-rs
  — Telegram bot to interface with libgen.
• zamazan4ik/npaperbot-telegram
  — Telegram bot for searching via C++ proposals.
• studentenherz/dlebot
  — A bot to query definitions of words from the Spanish Language Dictionary.
• fr0staman/fr0staman_bot
  — Feature rich Telegram game-like bot with pigs 🐽.
• franciscofigueira/transferBot
  — Telegram bot that notifies of crypto token transfers.

See 2500+ other public repositories using

>>

Contributing

See

.