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.
Highlights
- Declarative design.
teloxide
is based upondptree
, 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, 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 inserde-json
and command-line arguments instructopt
.
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:
# Unix-like
# Windows command line
# Windows PowerShell
- Make sure that your Rust compiler is up to date (
teloxide
currently requires rustc at least version 1.64):
# If you're using stable
# If you're using nightly
- Run
cargo new my_bot
, enter the directory and put these lines into yourCargo.toml
:
[]
= { = "0.11", = ["macros", "auto-send"] }
= "0.4"
= "0.4"
= { = "1.8", = ["rt-multi-thread", "macros"] }
API overview
The dices bot
This bot replies with a dice throw to each received message:
use *;
async
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
use ;
async
async
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 ;
type MyDialogue = ;
type HandlerResult = ;
async
async
async
async
async
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! 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/purchase.rs
.
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
— Telgram bot to interface with libgen.zamazan4ik/npaperbot-telegram
— Telegram bot for searching via C++ proposals.
mxseev/logram
— Utility that takes logs from anywhere and sends them to Telegram.alexkonovalov/PedigreeBot
— A Telegram bot for building family trees.Hermitter/tepe
— A CLI to command a bot to send messages and files over Telegram.myblackbeard/basketball-betting-bot
— The bot lets you bet on NBA games against your buddies.dracarys18/grpmr-rs
— Modular Telegram Group Manager Bot written in Rust.ArtHome12/cognito_bot
— The bot is designed to anonymize messages to a group.crapstone/hsctt
— A bot that converts HTTP status codes into text.
See 700+ other public repositories using teloxide
>>
Contributing
See CONRIBUTING.md
.