Telegram Bots skill for Codex

Done well means: one update source (polling or webhook, never both), webhook requests checked against secret_token, every callback query answered, user text escaped for the chosen parse mode, sends throttled below Telegram’s limits, and broadcasts only sent after the user confirms the audience and message.

Before writing code

1. Read AGENTS.md and the dependency file. Pick or confirm the library:

Stack	Default library
TypeScript or Node	grammY
Python (async)	python-telegram-bot v21+ (or aiogram 3 if already used)
Raw HTTP	https://api.telegram.org/bot<TOKEN>/<method> with JSON bodies

2. The token from @BotFather goes in TELEGRAM_BOT_TOKEN. Anyone with it controls the bot; if it leaked, the user must revoke it in BotFather. Never put the token in logs or URLs you print.
3. Choose update delivery:

Situation	Choose
Local development, single long-running process	Long polling (getUpdates)
Serverless or behind a load balancer, production	Webhook over HTTPS on port 443, 80, 88 or 8443

4. Messages to real users, group broadcasts and payments are outward-facing: confirm first. Bots cannot message a user who has not started the bot.

Calls to the Bot API need network access; in a Codex sandbox, ask for approval, or test handlers with the library’s test utilities or stubbed contexts.

grammY skeleton

import { Bot, InlineKeyboard, webhookCallback } from "grammy";

const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);

bot.command("start", async (ctx) => {
  const payload = ctx.match;                      // deep link: t.me/yourbot?start=<payload>
  await ctx.reply("Welcome. Choose a plan:", {
    reply_markup: new InlineKeyboard().text("Free", "plan:free").text("Pro", "plan:pro"),
  });
});

bot.callbackQuery(/^plan:(free|pro)$/, async (ctx) => {
  await ctx.answerCallbackQuery();                 // stops the loading spinner; do it first
  await ctx.editMessageText(`You chose ${ctx.match[1]}.`);
});

bot.catch((err) => console.error("update failed", err.ctx.update.update_id, err.error));

if (process.env.WEBHOOK) {
  app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_SECRET }));
} else {
  bot.start();                                     // long polling
}

python-telegram-bot skeleton

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    kb = InlineKeyboardMarkup([[InlineKeyboardButton("Free", callback_data="plan:free"),
                                InlineKeyboardButton("Pro", callback_data="plan:pro")]])
    await update.message.reply_text("Choose a plan:", reply_markup=kb)

async def on_plan(update: Update, context: ContextTypes.DEFAULT_TYPE):
    q = update.callback_query
    await q.answer()
    await q.edit_message_text(f"You chose {q.data.split(':', 1)[1]}.")

app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CallbackQueryHandler(on_plan, pattern=r"^plan:"))
app.run_polling()   # or app.run_webhook(listen="0.0.0.0", port=8443, url_path="telegram",
                    #   webhook_url="https://bot.example.com/telegram", secret_token=os.environ["TELEGRAM_SECRET"])

Webhook setup

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -d url=https://bot.example.com/telegram \
  -d secret_token="$TELEGRAM_SECRET" \
  -d drop_pending_updates=true \
  --data-urlencode 'allowed_updates=["message","callback_query"]'
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"

• Telegram sends the secret in the X-Telegram-Bot-Api-Secret-Token header; reject requests where it does not match. secret_token allows 1-256 characters of A-Z a-z 0-9 _ -.
• Return 200 quickly. Non-2xx responses make Telegram retry and back up the queue; getWebhookInfo shows pending_update_count and last_error_message.
• Setting a webhook disables getUpdates and the reverse (deleteWebhook). Running a polling dev copy against the production token steals or breaks production updates: use a separate dev bot.
• Dedupe on update_id if your handler is not idempotent.

Formatting

Parse mode	Escaping
HTML (recommended)	Escape <, >, & in user text; tags b, i, u, s, code, pre, a, blockquote, tg-spoiler
MarkdownV2	Backslash-escape all of _*[]()~>#+-={}.!, the pipe and the backtick outside entities

“Bad Request: can’t parse entities” almost always means unescaped user text. Text messages are capped at 4,096 characters, media captions at 1,024; split longer content.

Keyboards and state

• callback_data is 1-64 bytes. Encode action:id; keep anything larger in storage.
• Inline keyboards attach to a message; reply keyboards replace the user’s keyboard. Remove reply keyboards with remove_keyboard: true when done.
• Multi-step flows: grammY conversations plugin or sessions with persistent storage; python-telegram-bot ConversationHandler with a persistence backend. In-memory state is lost on deploy and breaks with more than one instance.

Rate limits and broadcasts

• Roughly 1 message per second per chat, 20 messages per minute per group, and about 30 messages per second overall for bulk sends. On 429 the response includes parameters.retry_after; wait that long.
• Use grammY’s auto-retry and transformer-throttler plugins, or python-telegram-bot’s AIORateLimiter, rather than hand-written sleeps.
• Broadcast: confirm audience and text with the user, send in throttled batches, record per-user results, and stop on users who blocked the bot (403 Forbidden) by marking them inactive.

Payments

Digital goods and services sold inside Telegram must use Telegram Stars: sendInvoice with currency XTR and an empty provider_token. Answer pre_checkout_query within 10 seconds, deliver on successful_payment, and store telegram_payment_charge_id for refunds (refundStarPayment). Physical goods can use a payment provider token from BotFather. Confirm before any live refund.

Gotchas

• Buttons spin forever: the callback query was never answered.
• Group bots in privacy mode only see commands, replies to them and mentions. Disable privacy in BotFather only when needed, then re-add the bot to the group.
• chat_id for supergroups and channels is negative (-100...); store it as a 64-bit integer.
• Editing a message to identical content returns “message is not modified”; ignore that error.
• Files: getFile gives a path valid for at least one hour; bot downloads are limited to 20 MB on the cloud Bot API.

Verification

• getWebhookInfo shows the right URL, pending_update_count near 0, no last_error_message.
• A request without the secret header gets 401 or 403 from your endpoint.
• Send user text containing <b> and _*[ through every reply path: no parse errors.
• Each button press stops spinning and updates the message.

Report template

**Library:** grammY 1.x, webhook at /telegram (secret_token checked), allowed_updates: message, callback_query
**Commands:** /start (deep link payload), /plan; inline keyboard plan:<id>
**State:** sessions in Redis; conversations plugin for onboarding
**Limits:** auto-retry + throttler; broadcast job batches 25/s, marks 403 users inactive
**Tested:** dev bot token only; production webhook switch awaiting approval