hitl-telegram

Implements Telegram-based human approval flows that pause and resume Celery job application tasks.

Updated May 19, 2026
One-click install
npx skills add https://github.com/Jessitoii/career-os --skill hitl-telegram-jessitoii
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hitl-telegram
Source: https://github.com/Jessitoii/career-os/tree/main/.agents/skills/hitl-telegram
Command: npx skills add https://github.com/Jessitoii/career-os --skill hitl-telegram-jessitoii

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires python-telegram-bot, celery, fastapi.

What problem does it solve? Automated job application agents inevitably hit questions only a human can answer, such as salary expectations or visa sponsorship. This Skill provides the pause-and-resume protocol that suspends a Celery task, asks the user via Telegram inline buttons, and resumes execution with the answer. ## Core Features & Use Cases - Task Suspension Protocol: Freeze browser state with screenshots and DOM snapshots, persist the pending question in the database, and log the interaction before pausing. - Telegram Approval Messages: Send inline keyboard buttons with job context and a screenshot so the user can answer with one tap. - Webhook Resume Flow: A FastAPI callback endpoint validates the callback, stores the answer, and re-queues the Celery task. - Timeout Handling: A scheduled check moves applications unanswered for 30 minutes to a deferred state. - Use Case: An agent filling a job form encounters a salary expectation field; it suspends, sends you a Telegram message with preset options, and continues the application the moment you tap an answer. ## Quick Start Ask the agent to pause the current job application task and send me a Telegram approval request with inline buttons for the salary expectation question.

Frequently Asked Questions about hitl-telegram

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I pause a Celery task to wait for user input?

Capture the browser state with a screenshot and DOM snapshot, update the application status to pending_approval in the database, send the Telegram question, then raise Ignore() so Celery marks the task as ignored rather than failed. The task is re-queued when the user answers.

How do I send Telegram inline buttons with python-telegram-bot?

Build InlineKeyboardButton objects with callback_data encoding the application ID and answer value, wrap them in an InlineKeyboardMarkup, and attach it to bot.send_photo or send_message. The user's tap triggers a callback_query to your webhook.

How do I handle Telegram webhook callbacks in FastAPI?

Create a POST endpoint that parses the callback_query data, splits out the application ID and answer value, updates the database status to approved, logs the interaction, and re-queues the Celery task with apply_task.delay.

Why is my suspended task stuck in pending_approval state?

A stuck SUSPENDED state usually means the webhook callback never fired or the application ID validation failed. Check that the Telegram webhook points to your FastAPI endpoint and that the timeout checker is running to defer unanswered tasks after 30 minutes.

What security precautions apply to Telegram approval bots?

Use a personal chat ID rather than a group so only one human approves, validate that the callback_data application ID exists in the database to prevent replay attacks, and never log salary values or personal data from Telegram messages.