Getter

A powerful and customizable Telegram userbot built with Telethon. Create custom plugins, automate tasks, and enhance your Telegram experience.

Warning

Your Telegram account may get banned if this userbot is misused. We are not responsible for any spam, violations, or account restrictions.

Use it at your own risk and review the Telegram API Terms.

Table of Contents

• Requirements
• Quick Start
  • Clone Repository
    • String Session
    • Config
• Deployments
  • Docker Compose
    • Full version
    • Lite version
  • Locally
  • Heroku
• Usage
• Update
• Custom Plugins
• Supports
• Contributing
• License

Requirements

• Python 3.14+
• Linux (Debian/Ubuntu)
• Telegram API_ID and API_HASH from API development tools

Quick Start

Follow these steps to set up and run Getter on your system.

Clone Repository

git clone https://github.com/kastaid/getter.git
cd getter

String Session

Generate STRING_SESSION by running python3 strgen.py, or directly:

python3 -c "import urllib.request as r;exec(r.urlopen('https://gist.githubusercontent.com/illvart/05a462d25ef1a99278201c5ee6b5ff14/raw').read())"

or using Docker:

docker run --rm -it python:3.14-alpine python3 -c "import urllib.request as r;exec(r.urlopen('https://gist.githubusercontent.com/illvart/05a462d25ef1a99278201c5ee6b5ff14/raw').read())"

Config

Create a .env file in the main directory and fill it with the example from example.env.

Deployments

Choose your preferred deployment method below.

Docker Compose

Deploy using Docker Compose for easy containerized deployment.

Full version

With FFmpeg.

git pull && \
  docker compose up -d --build && \
  docker compose logs -f

Stop or Restart

# stop
docker compose down
# restart
docker compose restart

Lite version

Without FFmpeg.

git pull && \
  docker compose -f lite-compose.yml up -d --build && \
  docker compose -f lite-compose.yml logs -f

Stop or Restart

# stop
docker compose -f lite-compose.yml down
# restart
docker compose -f lite-compose.yml restart

Locally

Run Getter locally on your machine or server (e.g., on Termux).

We recommend using uv for faster and more reliable Python package management.

Production

Using uv:

uv pip install -r requirements.txt
python3 -m getter

Using pip:

pip3 install -r requirements.txt
python3 -m getter

Development

Using uv:

uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt
python3 -m run --watch

Using pip:

pip3 install -r requirements.txt
pip3 install -r requirements-dev.txt
python3 -m run --watch

More commands: run python3 -m run -h.

Heroku

Deploy to Heroku with one click using the Container stack:

Usage

Once successfully deployed, test your Getter by sending .ping in any chat.

Command prefix:

• Default prefix is . (dot)
• If you set a custom HANDLER in your config, use that prefix instead (e.g., !ping, /ping)
• If NO_HANDLER is set to True, send commands without any prefix (e.g., ping)

Get all commands: .help - This will show you all available plugins, commands, and how to use them.

Update

Getter supports updating directly through Telegram or Git.

To update directly from your Telegram account, run this command in any chat:

.help updater

Then choose the update option to check for updates, view changelog, or update Getter.

For manual updates using Git:

git pull

If you updated from an older version and experience errors, fix your local repo with:

git fetch origin && git reset --hard origin/main

This is NOT required for fresh installs.

Custom Plugins

Create custom plugins at ./getter/plugins/custom/plugin_name.py.

Dynamic plugin management:

• Upload your plugin_name.py file anywhere in Telegram (plugin name must be unique)
• Reply to the file with .load to download, activate, or update the plugin
• Reply to the plugin file with .unload [plugin_name] to remove it

Example plugin:

from . import kasta_cmd


# Works everywhere (e.g., groups, personal chats)
@kasta_cmd(pattern="hi")
async def _(event):
    await event.eor("Hello **World**")


# Works only in personal chats
@kasta_cmd(pattern="hi", func=lambda e: e.is_private)
async def _(event):
    await event.eor("Hello **World**")


# Works only in channels
@kasta_cmd(pattern="hi", func=lambda e: e.is_channel and e.chat.broadcast)
async def _(event):
    await event.eor("Hello **World**")


# Works only in groups
@kasta_cmd(pattern="hi", func=lambda e: e.is_group)
async def _(event):
    await event.eor("Hello **World**")


# Works only in groups or channels
@kasta_cmd(pattern="hi", func=lambda e: not e.is_private)
async def _(event):
    await event.eor("Hello **World**")

For available modules, imports, functions, and methods, see __init__.py.

Supports

If you’re enjoying it or want to support development, feel free to donate. Thank you! ❤️

Contributing

Want to contribute? Read the Contributing.

License

Released under the AGPL-3.0 License.