Initial commit with translated description
This commit is contained in:
43
SKILL.md
Normal file
43
SKILL.md
Normal file
@@ -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.
|
||||||
6
_meta.json
Normal file
6
_meta.json
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"ownerId": "kn7ehv4at8yekzag31spcarxm180bev0",
|
||||||
|
"slug": "telegram",
|
||||||
|
"version": "1.0.1",
|
||||||
|
"publishedAt": 1770028389996
|
||||||
|
}
|
||||||
63
references/telegram-bot-api.md
Normal file
63
references/telegram-bot-api.md
Normal file
@@ -0,0 +1,63 @@
|
|||||||
|
# Telegram Bot API Field Notes
|
||||||
|
|
||||||
|
## 1) Base URL and request style
|
||||||
|
- Base format: `https://api.telegram.org/bot<token>/<method>`
|
||||||
|
- 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
|
||||||
26
references/telegram-commands-playbook.md
Normal file
26
references/telegram-commands-playbook.md
Normal file
@@ -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.”
|
||||||
42
references/telegram-request-templates.md
Normal file
42
references/telegram-request-templates.md
Normal file
@@ -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"]
|
||||||
|
}
|
||||||
|
```
|
||||||
23
references/telegram-update-routing.md
Normal file
23
references/telegram-update-routing.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user