telegram-signer 1.0.2

Telegram check-in scheduler with keyboard clicks and optional AI-assisted captcha handling.

Telegram Signer

Telegram Signer is a Python CLI tool for scheduled Telegram check-ins. It can send configured check-in messages, click inline keyboard buttons, handle topic IDs, keep SQLite check-in records, and optionally use an OpenAI-compatible API for image or math-style verification steps.

This fork is intentionally focused on check-ins only. It does not include extra dashboard or message-watching features.

Features

• Required account name in every command: telegram-signer <account> ...
• Scheduled check-in tasks with cron-style or time-style schedules
• Legacy config compatibility for existing signer config.json files
• SQLite check-in record storage with lazy migration from sign_record.json
• Telegram forum topic support through message_thread_id
• Action flow support:
  • send text
  • send dice
  • click a button by text
  • choose an option by image through an LLM
  • reply to a calculation prompt through an LLM
  • click captcha buttons according to a slot-machine dice result

Installation

Requires Python 3.10 or newer.

pip install -U telegram-signer

Command Format

The account name is required and comes before the command:

telegram-signer account_a login
telegram-signer account_a logout
telegram-signer account_a run task_name

Run multiple accounts with your shell by starting separate processes. Keep this to five accounts or fewer:

telegram-signer account_a run task_a &
telegram-signer account_b run task_b &
telegram-signer account_c run task_c &

Common Commands

telegram-signer account_a login
telegram-signer account_a logout
telegram-signer account_a list
telegram-signer account_a reconfig task_name
telegram-signer account_a run task_name
telegram-signer account_a run-force task_name
telegram-signer account_a list-records task_name
telegram-signer account_a migrate-records
telegram-signer account_a llm-config

Global options must be placed before the account name:

telegram-signer --workdir .signer account_a run task_name

Config Compatibility

Existing signer configs remain supported. The default path is:

<workdir>/telegram-signer/config/<task_name>/config.json

Older signer config versions are still migrated through the existing compatibility chain. Existing configs from the older path are still read and copied to the new path when loaded:

<workdir>/signs/<task_name>/config.json

Check-in records use SQLite at:

<workdir>/data.sqlite3

Legacy record files are still readable and can be migrated:

<workdir>/signs/<task_name>/<user_id>/sign_record.json
<workdir>/signs/<task_name>/sign_record.json

Example Config

{
  "chats": [
    {
      "chat_id": "@target_bot_or_group",
      "message_thread_id": null,
      "name": "daily check-in",
      "delete_after": null,
      "actions": [
        {"action": 1, "text": "/checkin"},
        {"action": 3, "text": "Check in"},
        {"action": 6, "if_dice_emoji": "🎰"}
      ],
      "action_interval": 1
    }
  ],
  "sign_at": "0 6 * * *",
  "random_seconds": 0,
  "sign_interval": 1
}

Action IDs:

ID	Action
1	send text
2	send dice
3	click keyboard button by text
4	choose option by image
5	reply to calculation prompt
6	solve slot-machine captcha buttons when an if_* condition matches

Slot-machine captcha solving is intentionally conditional. Add at least one of these fields to an action: 6 step:

{"action": 6, "if_dice_emoji": "🎰"}
{"action": 6, "if_text": "choose the symbols"}
{"action": 6, "if_regex": "slot|captcha|verification"}

If no if_* condition is present, the action is skipped.

LLM Configuration

LLM-backed actions read configuration from either environment variables or the workdir config file created by llm-config.

Environment variables:

OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL

Persistent workdir file:

<workdir>/.openai_config.json

Do not commit sessions, session strings, .env files, .openai_config.json, logs, or local SQLite databases.