Initial commit with translated description

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<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

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.”

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"]
+}
+```

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.