Telecharm userbot

Python 3.8 Codacy Badge
A powerful, fast and simple Telegram userbot written in Python 3 and based on Pyrogram 1.X. Currently in active WIP state, so feel free to contribute.

Starting up

Ensure you have installed the Python 3.8 or above before proceeding.

Preparations

  1. Git clone this repo.

    git clone https://github.com/WhiteMemory99/telecharm-userbot.git

  2. Visit https://my.telegram.org/apps to get your own api_id and api_hash.

  3. Rename .env.dist to .env and open it.

  4. Edit .env file: fill in your api_id, api_hash.

Docker deployment

Make sure you have docker.

  1. Build the image.
docker build -t telecharm-image .
  1. After building, start the userbot in interactive mode.
docker run -it -v pyrogram_sessions:/code/app/files --name telecharm-bot telecharm-image
  1. Enter your number, auth code from Telegram and 2FA password, if you have one.
  2. Exit the interactive mode with Ctrl+C or any other combination, depends on your system.
  3. Run the userbot with docker.
docker start telecharm-bot

Poetry deployment

Make sure you have poetry.

  1. Install requirements.

    poetry install

  2. You can also install an optional opencv-python module to extend .anime functionality.

    poetry install -E opencv

  3. Run the userbot with poetry.

    poetry run python app

Plain python deployment

  1. Install dependencies.

    pip install -r requirements.txt

  2. If you want to extend .anime functionality, install an optional opencv-python module.

    pip install opencv-python

  3. Run the userbot.

    python3 -m app

Usage

Telecharm will automatically gather, generate and update documentation for all the commands you have. No matter whether you use 3-rd party plugins or write them yourself.
At first launch, send .help to any chat to create your personal guide page.

Thanks for using Telecharm ?

Writing and using custom plugins

  1. By convention, all custom plugins are supposed to go to app/plugins/custom.

  2. Go to that folder and create a file named example.py as your first tutorial plugin.

  3. Insert the code below into the file and read all the comments to understand how it works.

Look at the example code

<div class="highlight highlight-source-python position-relative overflow-auto" data-snippet-clipboard-copy-content=""""
app/plugins/custom/example.py
This text would also appear in Telecharm guide as a module description.
"""
import asyncio
from pyrogram import filters

from app.config import conf
from app.utils import Client, Message # Use custom types for type-hinting
from app.utils.decorators import doc_exclude, doc_args

@Client.on_message(filters.me & filters.command("example", prefixes="."))
@doc_args("arg_name", ("date", "time")) # Let the Telecharm guide know about supported args (OPTIONAL)
@doc_exclude # This command will not appear in Telecharm guide, remove to check how the generation works ?
async def example_handler(client: Client, message: Message):
"""
This text would appear in Telecharm guide along with the command if it wasn't excluded.

You can even wrap it like that, or style with supported HTML text like THIS.
"""
await message.edit_text("Hey, this is the example of a custom plugin command.", message_ttl=conf.default_ttl)
# message_ttl is used for message clean up feature, so be sure to take it seriously.
# For general and short replies use default_ttl provided in conf.

if client.user_settings.get("clean_up"): # You can access and alter user settings with client.user_settings
await asyncio.sleep(1)
await message.reply_text(
"By the way, the clean up mode is on! So this message will disappear in 6 seconds.", message_ttl=6
)”>

"""
app/plugins/custom/example.py
This text would also appear in Telecharm guide as a module description.
"""
import asyncio
from pyrogram import filters

from app.config import conf
from app.utils import Client, Message  # Use custom types for type-hinting
from app.utils.decorators import doc_exclude, doc_args


@Client.on_message(filters.me & filters.command("example", prefixes="."))
@doc_args("arg_name", ("date", "time"))  # Let the Telecharm guide know about supported args (OPTIONAL)
@doc_exclude  # This command will not appear in Telecharm guide, remove to check how the generation works :)
async def example_handler(client: Client, message: Message):
    """
    This text would appear in Telecharm guide along with the command if it wasn't excluded.

    You can even wrap it like that, or style with supported HTML text like <b><i>THIS</b></i>.
    """
    await message.edit_text("Hey, this is the example of a custom plugin command.", message_ttl=conf.default_ttl)
    # message_ttl is used for message clean up feature, so be sure to take it seriously.
    # For general and short replies use default_ttl provided in conf.

    if client.user_settings.get("clean_up"):  # You can access and alter user settings with client.user_settings
        await asyncio.sleep(1)
        await message.reply_text(
            "By the way, the clean up mode is on! So this message will disappear in 6 seconds.", message_ttl=6
        )