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:

1. Ask the user for the missing value (bot token or chat ID).
2. 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:

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

1. Read ~/.claude/telegram.json to load bot_token and chat_id. If the file is missing, ask the user and create it.
2. Send a concise question with options and a deadline if needed.
3. Poll getUpdates until a reply arrives or a timeout is reached.
4. 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