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
• Custom Plugins
• Supports
• Contributing
• License

Requirements

• Python 3.13+
• 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 choosing Telethon at @strgen_bot or run python3 strgen.py.

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

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

Lite version

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

Locally

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

Production

pip3 install -r requirements.txt
python3 -m getter

Development

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:

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.

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.