Telegram Human-in-the-Loop Bot

Send questions and receive responses through a Telegram bot so an AI agent can keep moving when the user is away.

When to Use

• Agent needs approval or clarification

• Agent needs missing details or credentials

• User wants progress updates off-device

• User wants a human-in-the-loop handoff

Base URL

https://api.telegram.org

Credential Storage

Credentials are persisted in ~/.claude/telegram.json so they survive across sessions.

{ "bot_token": "<TELEGRAM_BOT_TOKEN>", "chat_id": "<TELEGRAM_CHAT_ID>" }

Loading Credentials

Before making any Telegram API call, read the config file:

cat ~/.claude/telegram.json

Parse bot_token and chat_id from the JSON output.

First-Time Setup

If ~/.claude/telegram.json does not exist or is missing a field:

• Ask the user for the missing value (bot token or chat ID).

• Write the complete JSON file:

mkdir -p ~/.claude cat > ~/.claude/telegram.json << 'EOF' { "bot_token": "<value>", "chat_id": "<value>" } EOF chmod 600 ~/.claude/telegram.json

Never log or echo the bot token in conversation output.

Authentication

Telegram uses a bot token in the URL path:

/bot{bot_token}/METHOD

Read bot_token from ~/.claude/telegram.json before every request.

Available Actions

1. Send Question to Human

Send a message that asks a clear question and includes required context.

POST /bot{token}/sendMessage

Body Parameters:

Parameter Required Description

chat_id

Yes User or group chat id

text

Yes Message text (ask for specific answer)

parse_mode

No MarkdownV2 or HTML

reply_markup

No Inline keyboard for quick responses

2. Poll for Replies

Fetch new messages and replies from the human.

GET /bot{token}/getUpdates?offset={update_id}&timeout={seconds}

Notes:

• Track the highest update_id and set offset=last_update_id+1 to avoid duplicates.

• Filter updates by message.chat.id to ensure the reply is from the right user.

3. Send Status Update

Use a short update when a task is long-running or blocked.

POST /bot{token}/sendMessage

Suggested Flow

• Read ~/.claude/telegram.json to load bot_token and chat_id . If the file is missing, ask the user and create it.

• Send a concise question with options and a deadline if needed.

• Poll getUpdates until a reply arrives or a timeout is reached.

• Confirm receipt and proceed based on the reply.

Response Format

All Telegram Bot API responses are JSON with:

• ok : boolean

• result : payload for the called method