commit f8912227dfd9ecb665ef7978ebaf3b8fbf8261f1 Author: zlei9 Date: Sun Mar 29 09:37:35 2026 +0800 Initial commit with translated description diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..d8b1d40 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,43 @@ +--- +name: telegram +description: "OpenClaw技能，用于设计Telegram Bot API工作流和命令驱动对话，使用直接HTTPS请求（无需SDK）。" +--- + +# Telegram Bot Skill (Advanced) + +## Purpose +Provide a clean, production-oriented guide for building Telegram bot workflows via the Bot API, focusing on command UX, update handling, and safe operations using plain HTTPS. + +## Best fit +- You want a command-first bot that behaves professionally. +- You need a reliable update flow (webhook or polling). +- You prefer direct HTTP calls instead of libraries. + +## Not a fit +- You require a full SDK or framework integration. +- You need complex media uploads and streaming in-process. + +## Quick orientation +- Read `references/telegram-bot-api.md` for endpoints, update types, and request patterns. +- Read `references/telegram-commands-playbook.md` for command UX and messaging style. +- Read `references/telegram-update-routing.md` for update normalization and routing rules. +- Read `references/telegram-request-templates.md` for HTTP payload templates. +- Keep this SKILL.md short and use references for details. + +## Required inputs +- Bot token and base API URL. +- Update strategy: webhook or long polling. +- Command list and conversation tone. +- Allowed update types and rate-limit posture. + +## Expected output +- A clear command design, update flow plan, and operational checklist. + +## Operational notes +- Prefer strict command routing: `/start`, `/help`, `/settings`, `/status`. +- Always validate incoming update payloads and chat context. +- Handle 429s with backoff and avoid message bursts. + +## Security notes +- Never log tokens. +- Use webhooks with a secret token header when possible. diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..3926e00 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn7ehv4at8yekzag31spcarxm180bev0", + "slug": "telegram", + "version": "1.0.1", + "publishedAt": 1770028389996 +} \ No newline at end of file diff --git a/references/telegram-bot-api.md b/references/telegram-bot-api.md new file mode 100644 index 0000000..a7a4675 --- /dev/null +++ b/references/telegram-bot-api.md @@ -0,0 +1,63 @@ +# Telegram Bot API Field Notes + +## 1) Base URL and request style +- Base format: `https://api.telegram.org/bot/` +- Use GET or POST with JSON or form-encoded payloads. +- File uploads use `multipart/form-data` and `attach://` references. + +## 2) Updates and delivery models +### Long polling +- `getUpdates` delivers updates with an `offset` cursor and `timeout`. + +### Webhook +- `setWebhook` switches the bot to webhook mode. +- Webhook URLs must be HTTPS. Check the official docs for port restrictions. + +### Update types (examples) +- `message`, `edited_message`, `channel_post`, `edited_channel_post` +- `inline_query`, `chosen_inline_result`, `callback_query` +- `shipping_query`, `pre_checkout_query`, `poll`, `poll_answer` + +Use `allowed_updates` to limit which updates you receive. + +## 3) High-traffic-safe patterns +- Use `allowed_updates` to reduce noise. +- Keep handlers idempotent (Telegram may retry). +- Return quickly from webhooks; process heavy work async. + +## 4) Common methods (non-exhaustive) +- `getMe`, `getUpdates`, `setWebhook` +- `sendMessage`, `editMessageText`, `deleteMessage` +- `sendPhoto`, `sendDocument`, `sendChatAction` +- `answerCallbackQuery`, `answerInlineQuery` + +## 5) Common fields (non-exhaustive) +### sendMessage +- `chat_id`, `text`, `parse_mode` +- `entities`, `disable_web_page_preview` +- `reply_markup` (inline keyboard, reply keyboard) + +### reply_markup (inline keyboard) +- `inline_keyboard`: array of button rows +- Buttons can contain `text` + `callback_data` or `url` + +### callback_query +- `id`, `from`, `message`, `data` + +### sendChatAction +- `action`: `typing`, `upload_photo`, `upload_document`, `upload_video`, `choose_sticker` + +## 6) Command UX checklist +- `/start`: greet, explain features, and show main commands. +- `/help`: include short examples and support contact. +- `/settings`: show toggles with inline keyboards. +- `/status`: show recent job results or queue size. + +## 7) Error handling +- `429`: back off and retry. +- `400`: validate chat_id, message length, and formatting. +- `403`: bot blocked or chat not accessible. + +## 8) Reference links +- https://core.telegram.org/bots/api +- https://core.telegram.org/bots/faq diff --git a/references/telegram-commands-playbook.md b/references/telegram-commands-playbook.md new file mode 100644 index 0000000..cb89251 --- /dev/null +++ b/references/telegram-commands-playbook.md @@ -0,0 +1,26 @@ +# Telegram Command Playbook + +## Command set (professional baseline) +- `/start`: greet, set expectations, and show main actions. +- `/help`: short help + examples. +- `/status`: show last job result, queue length, or uptime. +- `/settings`: show toggles via inline keyboard. +- `/about`: short bot description and support contact. + +## Command UX patterns +- Acknowledge fast, then do heavy work asynchronously. +- Prefer short replies with a single call-to-action. +- Always include “what next?” in `/start` and `/help`. + +## Inline keyboard patterns +- Use stable callback_data names (e.g., `settings:notifications:on`). +- Keep callbacks idempotent. + +## Message style guidelines +- Use MarkdownV2 or HTML consistently; avoid mixing. +- If using MarkdownV2, escape reserved characters. +- Keep single message length under safe limits; split when needed. + +## Examples (short) +- `/start` reply: “Hi! I can publish posts and send alerts. Try /help.” +- `/status` reply: “Queue: 2 jobs. Last run: success 2m ago.” diff --git a/references/telegram-request-templates.md b/references/telegram-request-templates.md new file mode 100644 index 0000000..581b193 --- /dev/null +++ b/references/telegram-request-templates.md @@ -0,0 +1,42 @@ +# Telegram Request Templates (HTTP) + +## sendMessage +POST `/sendMessage` +```json +{ + "chat_id": 123456789, + "text": "Hello", + "parse_mode": "HTML", + "disable_web_page_preview": true +} +``` + +## editMessageText +POST `/editMessageText` +```json +{ + "chat_id": 123456789, + "message_id": 42, + "text": "Updated", + "parse_mode": "HTML" +} +``` + +## answerCallbackQuery +POST `/answerCallbackQuery` +```json +{ + "callback_query_id": "1234567890", + "text": "Saved" +} +``` + +## setWebhook +POST `/setWebhook` +```json +{ + "url": "https://example.com/telegram/webhook", + "secret_token": "your-secret", + "allowed_updates": ["message","callback_query"] +} +``` diff --git a/references/telegram-update-routing.md b/references/telegram-update-routing.md new file mode 100644 index 0000000..e7bb676 --- /dev/null +++ b/references/telegram-update-routing.md @@ -0,0 +1,23 @@ +# Telegram Update Routing + +## Update normalization +- Normalize inbound updates to a single envelope: + - `update_id`, `chat_id`, `user_id`, `message_id`, `text`, `callback_data`, `type` +- This makes routing logic consistent across message types. + +## Routing rules +- If `callback_query` exists, handle callbacks first. +- Else if `message.text` starts with `/`, treat as command. +- Else fall back to default handler (help or menu). + +## Safe defaults +- Unknown command: reply with `/help` guidance. +- Unknown callback: answerCallbackQuery with a short notice. + +## Idempotency +- Keep a cache of processed `update_id` in case of retries. +- Ensure handlers can be safely re-run. + +## Error handling +- On 429: backoff and retry with jitter. +- On 400: validate payload length and parse mode.