TeamUltroid/Ultroid: A Pluggable Telethon Userbot With Voice and Video Calls

What Ultroid actually is, and who it is not for

Ultroid is a userbot, not a bot. The distinction matters more than the feature list. A Telegram bot talks to the Bot API under its own identity and only sees messages in chats where it was added. A userbot logs in as a human account through MTProto, which is the client protocol Telethon implements, so it sees what that account sees and can act wherever that account can. Ultroid's README describes it as "A stable pluggable Telegram userbot + Voice & Video Call music bot, based on Telethon."

That design decides the audience. It suits people who want to automate their own Telegram account: bulk actions, media handling, moderation helpers, and a music bot that joins voice chats. It does not suit anyone who wants a service other people can add to their groups under a separate identity. If you need a bot that strangers can invite and that survives your account being restricted, a Bot API project is the correct choice and Ultroid is the wrong tool.

The repository lists multi-language support and pytgcalls among its topics, and the plugin directory at plugins/ is where command implementations live. The string files sit in strings/, which is how the multi-language support is wired rather than being a runtime translation service.

How the plugin system and the database layer fit together

The runtime entry point is the pyUltroid package, started either by the startup script or by python -m pyUltroid. Commands are not defined in one large file. They are loaded from plugins/, and the README's own framing ("pluggable") tells you the intended extension path is to add a plugin rather than patch the core.

State is not kept in memory. Ultroid requires a database and accepts three backends: Redis through REDIS_URI and REDIS_PASSWORD, MongoDB through MONGO_URI, or a SQL database through DATABASE_URL. The README treats this as a choice of one, not a stack. That is a real architectural commitment: settings, saved chats, and per-user preferences survive a restart because they live in the database, and a fresh deployment with an empty database behaves like a fresh install even if the session is old.

Authentication is a single SESSION string. It is generated once, stored in the environment, and reused on every start. There is no second factor at boot and no device list in the configuration. Everything the account can do, the userbot can do, for as long as that string is valid.

Installing Ultroid locally and running the first command

The README offers three deployment routes: Heroku, Okteto, and a local machine. The local route is the one worth walking through, because it is the only one where you can see the moving parts.

Start by cloning the repository and entering it. The README gives these two commands verbatim.

Deploying Ultroid with Docker instead of a virtualenv

The repository ships a Dockerfile and a docker-compose.yml, which is the cleaner path if you do not want Python and its dependencies on the host. The Dockerfile builds from theteamultroid/ultroid:main, copies installer.sh into the image, runs it, sets the working directory to /root/TeamUltroid, and starts with bash startup. The timezone is set to Asia/Kolkata through the TZ environment variable, which you will want to change if your scheduled tasks should follow your own clock.

The compose file defines a single service named worker and passes the configuration through as environment variables. It marks API_ID, API_HASH, MONGO_URI, DATABASE_URL as defaulting to None, and BOT_TOKEN and LOG_CHANNEL as not mandatory. REDIS_URI, REDIS_PASSWORD and SESSION are listed without that annotation, which reflects the README's position that a session and one database are the minimum.

The session string is the security boundary

The README is direct about what SESSION is: "SessionString for your accounts login session." It is generated through one of several routes, including a Repl.it link, a wget one-liner for Linux and Termux, a PowerShell variant, and a Telegram bot called @SessionGeneratorBot.

Using a third-party bot to mint a login session for your account is the part of this project most worth pausing on. A session string is not a token you can rotate casually; it is the credential for the account. The README does not document a revocation procedure, a session expiry, or a way to list active sessions from inside Ultroid. If a string leaks, the remedy lives in Telegram's own client settings, not in this repository.

The same caution applies to the wget one-liners. They pull a script from a short URL and execute it. The README presents them as the easy path, and for many users they are, but the trust model is that the URL resolves to code you are willing to run as yourself.

Where Ultroid stops being the right answer

Ultroid's release history is thin at the top. The most recent tagged release in the repository is v0.7 from 2022-08-31, while the README badge advertises v0.8 and the last push to the default branch was 2026-07-23. Development clearly continues on main, but if you depend on tagged releases for reproducible deployments, you are pinning to something four years old or tracking a branch.

The second limit is that a userbot is a single point of failure tied to one account. Telegram can restrict or ban accounts that automate aggressively. Ultroid cannot protect you from that, and the README does not describe rate limiting or a safe-mode throttle. If your use case involves messaging many users who did not ask to hear from you, the failure mode is your account, not the software.

The third is scope. The repository's topics include telegrammusicbot and telegramvc, and the description promises voice and video calls. The README itself does not document the music commands, the required voice chat permissions, or what happens when the assistant account is not present. The assistant/ directory exists, which suggests a second account is involved in call handling, but the README does not explain that relationship. Treat music and VC as features you will have to learn from the code and the documentation site at ultroid.tech.

Ultroid compared with a Bot API framework

The obvious alternative is a Bot API framework such as a python-telegram-bot or aiogram style project, and the difference is not cosmetic. A Bot API bot is created through BotFather, gets its own username, and is added to groups by their owners. Its permissions are explicit, its token can be revoked from BotFather in seconds, and Telegram's terms are written with it in mind.

Ultroid inverts each of those. It has no separate identity, so it inherits every permission your account already has, including in chats where nobody expected an automated client. Revocation means ending a session, not clicking a button. And the plugin model, which is Ultroid's strongest feature, works equally well in a Bot API project: both load handlers from a directory and register commands.

So the choice is not about extensibility. It is about whether the automation needs to act as you. If it does, Ultroid is built for that. If it does not, the Bot API gives you the same plugin ergonomics with a credential you can kill.

Editorial conclusion

Adopt Ultroid if you already run your own Telegram account automation and want a plugin-driven userbot with a music bot attached, and you accept that the session string is the whole security boundary. Do not adopt it if you cannot host a database or answer for what your account does to other members. Verify first that the plugin you need exists in the repository, and read the AGPL-3.0 licence before you modify and expose anything built on it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. TeamUltroid/Ultroid on GitHub