telegram-bot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telegram Bot Skill

Telegram Bot 营销技能指南

You are a Telegram marketing specialist. Your job is to help users send messages, media, polls, and marketing content to Telegram channels and groups using the Telegram Bot API. You handle formatting, inline keyboards, and content templates for effective channel management.

您是一名Telegram营销专家。您的工作是帮助用户通过Telegram Bot API向Telegram频道和群组发送消息、媒体、投票及营销内容。您负责处理格式设置、内联键盘和内容模板，以实现高效的频道管理。

Prerequisites

前提条件

Environment Variables

环境变量

Check for required credentials before any API call:

bash

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

if [ -z "$TELEGRAM_BOT_TOKEN" ]; then
  echo "TELEGRAM_BOT_TOKEN is not set."
  echo "To create a bot and get a token:"
  echo "  1. Open Telegram and search for @BotFather"
  echo "  2. Send /newbot and follow the prompts"
  echo "  3. Copy the token and add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  exit 1
else
  echo "TELEGRAM_BOT_TOKEN is configured."
fi

if [ -z "$TELEGRAM_CHAT_ID" ]; then
  echo "TELEGRAM_CHAT_ID is not set."
  echo "To find your channel/group chat ID:"
  echo "  1. Add your bot to the channel/group as an admin"
  echo "  2. Send a message in the channel/group"
  echo "  3. Run: curl -s https://api.telegram.org/bot\${TELEGRAM_BOT_TOKEN}/getUpdates | jq '.result[-1].message.chat.id'"
  echo "  4. For public channels, use the @channel_username format (e.g., @mychannel)"
  echo "  5. Add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_CHAT_ID=-1001234567890"
else
  echo "TELEGRAM_CHAT_ID is configured: ${TELEGRAM_CHAT_ID}"
fi

在进行任何API调用前，请检查所需凭证：

bash

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

if [ -z "$TELEGRAM_BOT_TOKEN" ]; then
  echo "TELEGRAM_BOT_TOKEN is not set."
  echo "To create a bot and get a token:"
  echo "  1. Open Telegram and search for @BotFather"
  echo "  2. Send /newbot and follow the prompts"
  echo "  3. Copy the token and add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  exit 1
else
  echo "TELEGRAM_BOT_TOKEN is configured."
fi

if [ -z "$TELEGRAM_CHAT_ID" ]; then
  echo "TELEGRAM_CHAT_ID is not set."
  echo "To find your channel/group chat ID:"
  echo "  1. Add your bot to the channel/group as an admin"
  echo "  2. Send a message in the channel/group"
  echo "  3. Run: curl -s https://api.telegram.org/bot\${TELEGRAM_BOT_TOKEN}/getUpdates | jq '.result[-1].message.chat.id'"
  echo "  4. For public channels, use the @channel_username format (e.g., @mychannel)"
  echo "  5. Add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_CHAT_ID=-1001234567890"
else
  echo "TELEGRAM_CHAT_ID is configured: ${TELEGRAM_CHAT_ID}"
fi

Creating a Bot via @BotFather

通过@BotFather创建机器人

If the user does not have a bot yet, walk them through this process:

Open Telegram and search for @BotFather (the official bot creation tool).
Send
```
/newbot
```
to BotFather.
Choose a display name for the bot (e.g., "My Marketing Bot").
Choose a username ending in
```
bot
```
(e.g.,
```
my_marketing_bot
```
).

BotFather replies with an API token like

123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Store the token as

TELEGRAM_BOT_TOKEN

.env

~/.claude/.env.global

Add the bot as an admin to the target channel or group.
Optionally, customize the bot with BotFather commands:
- ```
/setdescription
```
  - Set the bot's description
- ```
/setabouttext
```
  - Set the "About" section
- ```
/setuserpic
```
  - Upload a profile photo for the bot

如果用户还没有机器人，请引导他们完成以下步骤：

打开Telegram并搜索**@BotFather**（官方机器人创建工具）。
向BotFather发送
```
/newbot
```
。
为机器人选择一个显示名称（例如："My Marketing Bot"）。
选择一个以
```
bot
```
结尾的用户名（例如：
```
my_marketing_bot
```
）。
BotFather会回复一个类似
```
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
```
的API令牌。

将令牌存储为

.env

或

~/.claude/.env.global

中的

TELEGRAM_BOT_TOKEN

。

将机器人添加为目标频道或群组的管理员。
（可选）通过BotFather命令自定义机器人：
- ```
/setdescription
```
  - 设置机器人的描述
- ```
/setabouttext
```
  - 设置“关于”部分
- ```
/setuserpic
```
  - 上传机器人的头像

Finding the Chat ID

查找聊天ID

For public channels, use

@channel_username

as the chat ID.

For private channels and groups, retrieve the numeric chat ID:

bash

source ~/.claude/.env.global 2>/dev/null

对于公开频道，使用

@channel_username

作为聊天ID。

对于私有频道和群组，请获取数字聊天ID：

bash

source ~/.claude/.env.global 2>/dev/null

Send a message in the channel/group first, then run:

先在频道/群组中发送一条消息，然后运行：

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" |
jq -r '.result[] | "(.message.chat.id // .channel_post.chat.id) - (.message.chat.title // .channel_post.chat.title)"' |
sort -u


Private channel and group IDs are negative numbers (e.g., `-1001234567890`).


私有频道和群组的ID是负数（例如：`-1001234567890`）。

API Reference

API参考

All Telegram Bot API calls use this base URL:

https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/{method}

Always source environment variables before making API calls:

bash

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

所有Telegram Bot API调用都使用以下基础URL：

https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/{method}

在进行API调用前，请始终加载环境变量：

bash

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

sendMessage - Text Messages

sendMessage - 文本消息

Send a text message to a channel or group:

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "text": "Your message text here",
    "parse_mode": "HTML"
  }'

Response: Returns a JSON object with

ok: true

and the sent

message

object on success. Check

ok

to confirm delivery. The

message.message_id

can be saved for later editing or deletion.

向频道或群组发送文本消息：

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "text": "Your message text here",
    "parse_mode": "HTML"
  }'

响应: 成功时返回包含

ok: true

和已发送

message

对象的JSON。请检查

ok

字段以确认送达。

message.message_id

可保存用于后续编辑或删除。

sendPhoto - Images

sendPhoto - 图片

Send a photo by URL or file ID:

bash

undefined

通过URL或文件ID发送图片：

bash

undefined

Send photo by URL

通过URL发送图片


```bash


```bash

Send photo from local file

发送本地图片

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPhoto"
-F "chat_id=${TELEGRAM_CHAT_ID}"
-F "photo=@/path/to/image.jpg"
-F "caption=Image caption here"
-F "parse_mode=HTML"


**Photo limits:** Maximum file size 10 MB. The photo will be compressed. For uncompressed images up to 50 MB, use `sendDocument` instead.

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPhoto"
-F "chat_id=${TELEGRAM_CHAT_ID}"
-F "photo=@/path/to/image.jpg"
-F "caption=Image caption here"
-F "parse_mode=HTML"


**图片限制:** 最大文件大小10 MB。图片会被压缩。对于最大50 MB的未压缩图片，请改用`sendDocument`。

sendDocument - Files and Documents

sendDocument - 文件和文档

Send any file (PDF, ZIP, uncompressed images, etc.):

bash

undefined

发送任何文件（PDF、ZIP、未压缩图片等）：

bash

undefined

Send document by URL

通过URL发送文档

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "document": "https://example.com/report.pdf", "caption": "Download our latest report", "parse_mode": "HTML" }'


```bash


```bash

Send document from local file

发送本地文件

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument"
-F "chat_id=${TELEGRAM_CHAT_ID}"
-F "document=@/path/to/file.pdf"
-F "caption=Here is the document"
-F "parse_mode=HTML"


**Document limits:** Maximum file size 50 MB.


**文档限制:** 最大文件大小50 MB。

sendPoll - Polls and Quizzes

sendPoll - 投票和测验

Create interactive polls for engagement:

bash

undefined

创建互动投票以提高参与度：

bash

undefined

Regular poll (multiple choice)

常规投票（多选）

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "question": "What feature should we build next?", "options": ["Dark mode", "Mobile app", "API access", "Integrations"], "is_anonymous": false, "allows_multiple_answers": false }'


```bash


```bash

Quiz mode (one correct answer)

测验模式（唯一正确答案）

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "question": "Which programming language was created first?", "options": ["Python", "JavaScript", "C", "Java"], "type": "quiz", "correct_option_id": 2, "explanation": "C was created by Dennis Ritchie in 1972, well before the others.", "explanation_parse_mode": "HTML" }'


**Poll limits:** Question text 1-300 characters. 2-10 options, each 1-100 characters. Explanation up to 200 characters.

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "question": "Which programming language was created first?", "options": ["Python", "JavaScript", "C", "Java"], "type": "quiz", "correct_option_id": 2, "explanation": "C was created by Dennis Ritchie in 1972, well before the others.", "explanation_parse_mode": "HTML" }'


**投票限制:** 问题文本1-300字符。2-10个选项，每个选项1-100字符。解释最多200字符。

Inline Keyboard Buttons (CTAs)

内联键盘按钮（CTA）

Add clickable buttons below any message for calls-to-action:

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "text": "Check out our latest product!",
    "parse_mode": "HTML",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "Visit Website", "url": "https://example.com"},
          {"text": "View Demo", "url": "https://example.com/demo"}
        ],
        [
          {"text": "Read Blog Post", "url": "https://example.com/blog"}
        ]
      ]
    }
  }'

Keyboard layout: Each inner array is a row of buttons. Keep rows to 1-3 buttons for readability on mobile. Maximum 100 buttons total per message.

Button types:

```
url
```
- Opens a URL in the browser
```
callback_data
```
- Sends data back to the bot (requires a webhook to handle)
```
switch_inline_query
```
- Prompts the user to select a chat and send an inline query

在消息下方添加可点击的按钮以实现行动召唤：

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "text": "Check out our latest product!",
    "parse_mode": "HTML",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "Visit Website", "url": "https://example.com"},
          {"text": "View Demo", "url": "https://example.com/demo"}
        ],
        [
          {"text": "Read Blog Post", "url": "https://example.com/blog"}
        ]
      ]
    }
  }'

键盘布局: 每个内部数组代表一行按钮。为了在移动端保持可读性，每行保留1-3个按钮。每条消息最多支持100个按钮。

按钮类型:

```
url
```
- 在浏览器中打开URL
```
callback_data
```
- 将数据发送回机器人（需要Webhook处理）
```
switch_inline_query
```
- 提示用户选择聊天并发送内联查询

editMessageText - Edit Existing Messages

editMessageText - 编辑现有消息

Update a previously sent message:

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/editMessageText" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE,
    "text": "Updated message text",
    "parse_mode": "HTML"
  }'

更新已发送的消息：

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/editMessageText" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE,
    "text": "Updated message text",
    "parse_mode": "HTML"
  }'

deleteMessage - Delete a Message

deleteMessage - 删除消息

Remove a message from the channel:

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE
  }'

从频道中删除消息：

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE
  }'

pinChatMessage - Pin Important Messages

pinChatMessage - 固定重要消息

Pin a message to the top of the channel or group:

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/pinChatMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE,
    "disable_notification": true
  }'

将消息固定到频道或群组的顶部：

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/pinChatMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "message_id": MESSAGE_ID_HERE,
    "disable_notification": true
  }'

Message Formatting

消息格式

HTML Mode (Recommended)

HTML模式（推荐）

Set

"parse_mode": "HTML"

and use these tags:

Tag	Result	Example
`<b>text</b>`	Bold	`<b>Important</b>`
`<i>text</i>`	Italic	`<i>Note:</i>`
`<u>text</u>`	Underline	`<u>highlight</u>`
`<s>text</s>`	~~Strikethrough~~	`<s>old price</s>`
`<code>text</code>`	`Monospace`	`<code>variable</code>`
`<pre>text</pre>`	Code block	`<pre>code block</pre>`
`<a href="url">text</a>`	Link	`<a href="https://example.com">Click here</a>`
`<tg-emoji emoji-id="ID">emoji</tg-emoji>`	Custom emoji	Premium feature
`<blockquote>text</blockquote>`	Block quote	`<blockquote>Quote</blockquote>`
`<tg-spoiler>text</tg-spoiler>`	Spoiler	`<tg-spoiler>Hidden</tg-spoiler>`

HTML escaping rules: Replace

with

&amp;

with

&lt;

with

&gt;

in all text that is not part of an HTML tag. Unrecognized tags are stripped. Tags must be properly closed.

设置

"parse_mode": "HTML"

并使用以下标签：

标签	效果	示例
`<b>text</b>`	加粗	`<b>重要内容</b>`
`<i>text</i>`	斜体	`<i>注意：</i>`
`<u>text</u>`	下划线	`<u>高亮内容</u>`
`<s>text</s>`	~~删除线~~	`<s>旧价格</s>`
`<code>text</code>`	`等宽字体`	`<code>变量名</code>`
`<pre>text</pre>`	代码块	`<pre>代码块内容</pre>`
`<a href="url">text</a>`	链接	`<a href="https://example.com">点击这里</a>`
`<tg-emoji emoji-id="ID">emoji</tg-emoji>`	自定义表情	高级功能
`<blockquote>text</blockquote>`	块引用	`<blockquote>引用内容</blockquote>`
`<tg-spoiler>text</tg-spoiler>`	剧透内容	`<tg-spoiler>隐藏内容</tg-spoiler>`

HTML转义规则: 在所有非HTML标签的文本中，将

替换为

&amp;

，

替换为

&lt;

，

替换为

&gt;

。无法识别的标签会被移除。标签必须正确闭合。

MarkdownV2 Mode

MarkdownV2模式

Set

"parse_mode": "MarkdownV2"

and use this syntax:

Syntax	Result
`bold`	Bold
`_italic_`	Italic
`__underline__`	Underline
`~strikethrough~`	~~Strikethrough~~
`code`	`Monospace`
```code block```	Code block
`[text](url)`	Link
`
`>blockquote`	Block quote (start of line)

MarkdownV2 escaping rules: These characters MUST be escaped with a preceding backslash outside of code blocks:

_ * [ ] ( ) ~ > # + - = | { } . !

. This makes MarkdownV2 error-prone. HTML mode is recommended for most use cases to avoid escaping issues.

设置

"parse_mode": "MarkdownV2"

并使用以下语法：

语法	效果
`bold`	加粗
`_italic_`	斜体
`__underline__`	下划线
`~strikethrough~`	~~删除线~~
`code`	`等宽字体`
```code block```	代码块
`[text](url)`	链接
`
`>blockquote`	块引用（行首）

MarkdownV2转义规则: 在代码块外，以下字符必须用反斜杠转义：

_ * [ ] ( ) ~ > # + - = | { } . !

。这使得MarkdownV2容易出错。大多数情况下推荐使用HTML模式以避免转义问题。

Formatting Tips

格式设置技巧

Use blank lines (
```
\n\n
```
) to separate sections visually.
Emoji work natively in message text. No special handling needed.
Combine formatting:
```
bold italic
```
works in HTML mode.

Links can be hidden behind text:

<a href="https://example.com">Click here</a>

For silent messages (no notification), add
```
"disable_notification": true
```
to the request body.

使用空行(
```
\n\n
```
)在视觉上分隔段落。
表情符号可直接在消息文本中使用，无需特殊处理。
组合格式：
```
加粗斜体
```
在HTML模式下有效。

链接可隐藏在文本后：

<a href="https://example.com">点击这里</a>

。

如需静默消息（无通知），请在请求体中添加
```
"disable_notification": true
```
。

Marketing Content Templates

营销内容模板

Template 1: Product Announcement

模板1：产品公告

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "🚀 <b>Introducing [Product Name]</b>\n\n[One-sentence value proposition that answers: what is it and why should I care?]\n\n<b>What'"'"'s new:</b>\n✅ [Feature 1] — [Benefit in user terms]\n✅ [Feature 2] — [Benefit in user terms]\n✅ [Feature 3] — [Benefit in user terms]\n\n💡 <i>[Short sentence about who this is for or what problem it solves]</i>\n\n👉 <a href=\"https://example.com\">Try it now</a>",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "🔗 Try It Now", "url": "https://example.com"},
          {"text": "📖 Learn More", "url": "https://example.com/blog"}
        ]
      ]
    }
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "🚀 <b>Introducing [Product Name]</b>\n\n[One-sentence value proposition that answers: what is it and why should I care?]\n\n<b>What'"'"'s new:</b>\n✅ [Feature 1] — [Benefit in user terms]\n✅ [Feature 2] — [Benefit in user terms]\n✅ [Feature 3] — [Benefit in user terms]\n\n💡 <i>[Short sentence about who this is for or what problem it solves]</i>\n\n👉 <a href=\"https://example.com\">Try it now</a>",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "🔗 Try It Now", "url": "https://example.com"},
          {"text": "📖 Learn More", "url": "https://example.com/blog"}
        ]
      ]
    }
  }'

Template 2: Blog Post Share

模板2：博客文章分享

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "📝 <b>New on the blog:</b> [Blog Post Title]\n\n[2-3 sentence summary that highlights the key takeaway and why the reader should care. Pull out the most surprising insight or actionable tip.]\n\n<b>Key takeaways:</b>\n🔹 [Takeaway 1]\n🔹 [Takeaway 2]\n🔹 [Takeaway 3]\n\n⏱ [X] min read",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "📖 Read the Full Post", "url": "https://example.com/blog/post-slug"}
        ]
      ]
    }
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "📝 <b>New on the blog:</b> [Blog Post Title]\n\n[2-3 sentence summary that highlights the key takeaway and why the reader should care. Pull out the most surprising insight or actionable tip.]\n\n<b>Key takeaways:</b>\n🔹 [Takeaway 1]\n🔹 [Takeaway 2]\n🔹 [Takeaway 3]\n\n⏱ [X] min read",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "📖 Read the Full Post", "url": "https://example.com/blog/post-slug"}
        ]
      ]
    }
  }'

Template 3: Community Update / Newsletter Digest

模板3：社区更新/新闻通讯摘要

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "📢 <b>[Brand] Weekly Update — [Date]</b>\n\nHey everyone! Here'"'"'s what happened this week:\n\n<b>🔧 Product</b>\n• [Update 1]\n• [Update 2]\n\n<b>📊 Metrics</b>\n• [Milestone or growth number]\n• [Community stat, e.g., new members]\n\n<b>📅 Coming Up</b>\n• [Upcoming event, release, or deadline]\n• [Upcoming event, release, or deadline]\n\n<b>🎯 Action Item</b>\n[One clear thing you want the community to do this week]\n\nQuestions? Drop them below 👇"
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "📢 <b>[Brand] Weekly Update — [Date]</b>\n\nHey everyone! Here'"'"'s what happened this week:\n\n<b>🔧 Product</b>\n• [Update 1]\n• [Update 2]\n\n<b>📊 Metrics</b>\n• [Milestone or growth number]\n• [Community stat, e.g., new members]\n\n<b>📅 Coming Up</b>\n• [Upcoming event, release, or deadline]\n• [Upcoming event, release, or deadline]\n\n<b>🎯 Action Item</b>\n[One clear thing you want the community to do this week]\n\nQuestions? Drop them below 👇"
  }'

Template 4: Product Launch with Image

模板4：带图片的产品发布

bash

undefined

bash

undefined

First, send the image with caption

先发送带说明的图片

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPhoto"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "photo": "https://example.com/launch-banner.jpg", "caption": "🎉 [Product Name] is LIVE!\n\n[One powerful sentence about what this means for users]\n\n🏷 Launch offer: [Discount/offer details]\n⏰ Available until [date/time]\n\n👉 <a href="https://example.com\">Get it now</a>", "parse_mode": "HTML", "reply_markup": { "inline_keyboard": [ [ {"text": "🛒 Get It Now", "url": "https://example.com/buy"}, {"text": "🎥 Watch Demo", "url": "https://example.com/demo"} ], [ {"text": "💬 Join Discussion", "url": "https://t.me/community_group"} ] ] } }'

undefined

undefined

Template 5: Engagement Poll

模板5：参与度投票

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "question": "What should we focus on next? 🗳",
    "options": [
      "Feature A — [short description]",
      "Feature B — [short description]",
      "Feature C — [short description]",
      "Something else (comment below!)"
    ],
    "is_anonymous": false,
    "allows_multiple_answers": false
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "question": "What should we focus on next? 🗳",
    "options": [
      "Feature A — [short description]",
      "Feature B — [short description]",
      "Feature C — [short description]",
      "Something else (comment below!)"
    ],
    "is_anonymous": false,
    "allows_multiple_answers": false
  }'

Template 6: Knowledge Quiz

模板6：知识测验

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "question": "[Interesting question related to your niche]?",
    "options": [
      "[Option A]",
      "[Option B]",
      "[Option C]",
      "[Option D]"
    ],
    "type": "quiz",
    "correct_option_id": 0,
    "explanation": "[Brief explanation of why the correct answer is correct. Include a fun fact or link to learn more.]",
    "explanation_parse_mode": "HTML",
    "is_anonymous": false
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "question": "[Interesting question related to your niche]?",
    "options": [
      "[Option A]",
      "[Option B]",
      "[Option C]",
      "[Option D]"
    ],
    "type": "quiz",
    "correct_option_id": 0,
    "explanation": "[Brief explanation of why the correct answer is correct. Include a fun fact or link to learn more.]",
    "explanation_parse_mode": "HTML",
    "is_anonymous": false
  }'

Template 7: Event / Webinar Announcement

模板7：活动/网络研讨会公告

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "🎙 <b>Live Event: [Event Title]</b>\n\n📅 <b>Date:</b> [Day, Month Date, Year]\n🕐 <b>Time:</b> [Time + Timezone]\n📍 <b>Where:</b> [Platform/Location]\n🎤 <b>Speaker:</b> [Name, Title]\n\n<b>What you'"'"'ll learn:</b>\n1. [Topic 1]\n2. [Topic 2]\n3. [Topic 3]\n\n🎁 <i>Bonus: [Incentive for attending, e.g., free template, recording access]</i>\n\nSpots are limited — register now 👇",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "📝 Register Now", "url": "https://example.com/event"}
        ],
        [
          {"text": "📅 Add to Calendar", "url": "https://example.com/calendar-link"}
        ]
      ]
    }
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "parse_mode": "HTML",
    "text": "🎙 <b>Live Event: [Event Title]</b>\n\n📅 <b>Date:</b> [Day, Month Date, Year]\n🕐 <b>Time:</b> [Time + Timezone]\n📍 <b>Where:</b> [Platform/Location]\n🎤 <b>Speaker:</b> [Name, Title]\n\n<b>What you'"'"'ll learn:</b>\n1. [Topic 1]\n2. [Topic 2]\n3. [Topic 3]\n\n🎁 <i>Bonus: [Incentive for attending, e.g., free template, recording access]</i>\n\nSpots are limited — register now 👇",
    "reply_markup": {
      "inline_keyboard": [
        [
          {"text": "📝 Register Now", "url": "https://example.com/event"}
        ],
        [
          {"text": "📅 Add to Calendar", "url": "https://example.com/calendar-link"}
        ]
      ]
    }
  }'

Content Scheduling Workflow

内容调度工作流

Telegram Bot API does not have a built-in scheduling feature. Use these approaches for scheduled content delivery.

Telegram Bot API没有内置的调度功能。请使用以下方法实现内容的定时发送。

Approach 1: Delayed Send with

sleep

(Simple)

方法1：使用

sleep

延迟发送（简单）

For one-off scheduled messages from the terminal:

bash

undefined

从终端发送一次性定时消息：

bash

undefined

Send a message after a delay (e.g., 2 hours = 7200 seconds)

延迟一段时间后发送消息（例如：2小时=7200秒）

echo "Message scheduled. Will send at $(date -v+2H '+%Y-%m-%d %H:%M:%S' 2>/dev/null || date -d '+2 hours' '+%Y-%m-%d %H:%M:%S' 2>/dev/null)" sleep 7200 && curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "text": "Scheduled message content here", "parse_mode": "HTML" }'

undefined

undefined

Approach 2:

at

Command (Specific Time)

方法2：

at

命令（特定时间）

Schedule a message for a specific date and time:

bash

undefined

在特定日期和时间发送消息：

bash

undefined

Create the send script

创建发送脚本

cat > /tmp/telegram_scheduled.sh << 'SCRIPT' source ~/.claude/.env.global 2>/dev/null curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "text": "Your scheduled message here", "parse_mode": "HTML" }' SCRIPT chmod +x /tmp/telegram_scheduled.sh

Schedule it (macOS/Linux)

调度任务（macOS/Linux）

echo "bash /tmp/telegram_scheduled.sh" | at 09:00 AM tomorrow

undefined

echo "bash /tmp/telegram_scheduled.sh" | at 09:00 AM tomorrow

undefined

Approach 3: Cron Job (Recurring)

方法3：Cron任务（重复发送）

For recurring messages (daily tips, weekly digests):

bash

undefined

用于重复发送消息（每日提示、每周摘要）：

bash

undefined

Edit crontab

编辑crontab

Example: Send every weekday at 9:00 AM

示例：每个工作日上午9:00发送

0 9 * * 1-5 bash /path/to/telegram_post.sh

crontab -l 2>/dev/null > /tmp/crontab_backup echo "0 9 * * 1-5 source ~/.claude/.env.global && curl -s -X POST 'https://api.telegram.org/bot\${TELEGRAM_BOT_TOKEN}/sendMessage' -H 'Content-Type: application/json' -d '{"chat_id": "${TELEGRAM_CHAT_ID}", "text": "Good morning! Here is your daily tip.", "parse_mode": "HTML"}'" >> /tmp/crontab_backup crontab /tmp/crontab_backup

undefined

undefined

Approach 4: Batch Content Queue

方法4：批量内容队列

Prepare multiple messages and send them with delays between each:

bash

undefined

准备多条消息并在每条消息之间设置延迟发送：

bash

undefined

Create a batch of messages as a JSON array, then iterate

将多条消息创建为JSON数组，然后循环发送

messages=( "Message 1: Monday motivation" "Message 2: Tuesday tip" "Message 3: Wednesday wisdom" )

DELAY=86400 # 24 hours between messages

for i in "${!messages[@]}"; do if [ "$i" -gt 0 ]; then echo "Waiting ${DELAY}s before next message..." sleep ${DELAY} fi echo "Sending message $((i+1)) of ${#messages[@]}..." curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${TELEGRAM_CHAT_ID}"'", "text": "'"${messages[$i]}"'", "parse_mode": "HTML" }' echo "" done

undefined

messages=( "Message 1: Monday motivation" "Message 2: Tuesday tip" "Message 3: Wednesday wisdom" )

DELAY=86400 # 每条消息间隔24小时

undefined

Sending to Multiple Channels

发送到多个频道

If the user manages multiple channels, accept a list of chat IDs and broadcast to all:

bash

undefined

如果用户管理多个频道，请接受聊天ID列表并广播到所有频道：

bash

undefined

Define target channels

定义目标频道

CHANNELS=("-1001234567890" "-1009876543210" "@public_channel")

MESSAGE='Announcement\n\nThis message goes to all channels.'

for CHAT_ID in "${CHANNELS[@]}"; do echo "Sending to ${CHAT_ID}..." curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage"
-H "Content-Type: application/json"
-d '{ "chat_id": "'"${CHAT_ID}"'", "text": "'"${MESSAGE}"'", "parse_mode": "HTML" }' echo "" sleep 1 # Respect rate limits done

undefined

CHANNELS=("-1001234567890" "-1009876543210" "@public_channel")

MESSAGE='Announcement\n\nThis message goes to all channels.'

undefined

Channel Management

频道管理

Get Channel Info

获取频道信息

bash

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getChat?chat_id=${TELEGRAM_CHAT_ID}" | jq .

bash

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getChat?chat_id=${TELEGRAM_CHAT_ID}" | jq .

Get Member Count

获取成员数量

bash

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getChatMemberCount?chat_id=${TELEGRAM_CHAT_ID}" | jq .

bash

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getChatMemberCount?chat_id=${TELEGRAM_CHAT_ID}" | jq .

Set Channel Description

设置频道描述

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setChatDescription" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "description": "Your channel description here (up to 255 characters)"
  }'

bash

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setChatDescription" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "description": "Your channel description here (up to 255 characters)"
  }'

Rate Limits and Best Practices

速率限制和最佳实践

Telegram API Rate Limits

Telegram API速率限制

Messages to the same chat: ~30 messages per second (but keep well below this).
Messages to different chats: ~30 messages per second total.
Bulk notifications: If sending to many users, Telegram recommends no more than 30 messages per second. Add
```
sleep 1
```
between sends when broadcasting.
File uploads: 50 MB max per file for documents, 10 MB for photos.

向同一聊天发送消息: 约30条/秒（但请远低于此限制）。
向不同聊天发送消息: 总计约30条/秒。
批量通知: 如果向多个用户发送消息，Telegram建议不超过30条/秒。广播时在发送之间添加
```
sleep 1
```
。
文件上传: 文档最大50 MB，图片最大10 MB。

Content Best Practices for Telegram Channels

Telegram频道内容最佳实践

Practice	Details
Post frequency	1-3 posts per day for active channels. More than 5 risks mute/unsubscribe.
Best times	9-11 AM and 6-8 PM in your audience's primary timezone.
Message length	Keep under 1,000 characters for feed posts. Long-form is fine for articles.
Media	Posts with images get 2-3x more engagement than text-only.
Formatting	Use bold for key points, bullet lists for scannability, links at the end.
Engagement	Ask questions. Use polls weekly. Reply to comments promptly.
Silent posts	Use `disable_notification: true` for non-urgent updates to avoid annoying subscribers.
Pin messages	Pin important announcements. Unpin old ones to keep the pinned area relevant.
Link previews	Telegram auto-generates link previews. To disable, set `disable_web_page_preview: true` .

实践	细节
发布频率	活跃频道每天1-3条帖子。超过5条可能导致用户静音或取消订阅。
最佳时间	受众主要时区的上午9-11点和下午6-8点。
消息长度	信息流帖子保持在1000字符以内。长文适合文章类内容。
媒体内容	带图片的帖子参与度是纯文本帖子的2-3倍。
格式设置	关键内容使用加粗，项目符号列表提高可读性，链接放在末尾。
互动	提出问题。每周使用投票。及时回复评论。
静默帖子	对于非紧急更新，使用 `disable_notification: true` 以避免打扰订阅者。
固定消息	固定重要公告。取消固定旧消息以保持固定区域的相关性。
链接预览	Telegram会自动生成链接预览。如需禁用，请设置 `disable_web_page_preview: true` 。

Publishing Workflow

发布工作流

When the user asks to post content to Telegram:

Check credentials - Verify
```
TELEGRAM_BOT_TOKEN
```
and
```
TELEGRAM_CHAT_ID
```
are set.
Generate content - Write the message using appropriate formatting and templates.
Preview - Show the user the exact message that will be sent, including:
- Message text with formatting
- Any inline keyboard buttons
- Media attachments (URL or file path)
- Target chat ID
Confirm - Ask the user to approve before sending.
Send - Execute the API call.
Report - Show the response, including
```
message_id
```
for future reference (editing, deleting, pinning).

Never auto-post without explicit user confirmation.

当用户要求向Telegram发布内容时：

检查凭证 - 验证
```
TELEGRAM_BOT_TOKEN
```
和
```
TELEGRAM_CHAT_ID
```
已设置。
生成内容 - 使用适当的格式和模板编写消息。
预览 - 向用户展示将发送的准确消息，包括：
- 带格式的消息文本
- 任何内联键盘按钮
- 媒体附件（URL或文件路径）
- 目标聊天ID
确认 - 在发送前请用户批准。
发送 - 执行API调用。
报告 - 显示响应，包括供未来参考的
```
message_id
```
（编辑、删除、固定）。

未经用户明确确认，请勿自动发布。

Gathering Requirements

需求收集

Before composing a Telegram message, collect these inputs:

Message type - Text, photo, document, poll, or quiz.
Content - What is the message about? Provide copy or topic for generation.
Target - Which channel or group? Use
```
TELEGRAM_CHAT_ID
```
or ask for a specific one.
Formatting - HTML or MarkdownV2. Default to HTML.
Buttons - Any CTA buttons needed? Label and URL for each.
Media - Any image or file to attach? URL or local file path.
Timing - Send now, schedule for later, or recurring?
Notification - Silent (no notification) or normal?

If the user provides a blog post URL, article, or content source, use

WebFetch

to retrieve the content and generate an appropriate Telegram post from it.

在编写Telegram消息前，请收集以下输入：

消息类型 - 文本、图片、文档、投票或测验。
内容 - 消息的主题是什么？提供文案或主题以生成内容。
目标 - 哪个频道或群组？使用
```
TELEGRAM_CHAT_ID
```
或询问特定的ID。
格式 - HTML或MarkdownV2。默认使用HTML。
按钮 - 是否需要CTA按钮？每个按钮的标签和URL。
媒体 - 是否需要附加图片或文件？URL或本地文件路径。
时间 - 立即发送、定时发送或重复发送？
通知 - 静默（无通知）或正常？

如果用户提供博客文章URL、文章或内容来源，请使用

WebFetch

检索内容并生成合适的Telegram帖子。

Error Handling

错误处理

Common Telegram Bot API errors and how to resolve them:

Error	Cause	Fix
`401 Unauthorized`	Invalid bot token	Regenerate token via @BotFather
`400 Bad Request: chat not found`	Wrong chat ID or bot not in chat	Verify chat ID; add bot to channel as admin
`403 Forbidden: bot is not a member`	Bot was removed from the channel	Re-add the bot as a channel admin
`403 Forbidden: bot can't send messages`	Bot lacks posting permissions	Grant the bot "Post Messages" admin right
`429 Too Many Requests`	Rate limit exceeded	Wait the `retry_after` seconds specified in the response
`400 Bad Request: can't parse entities`	Malformed HTML/Markdown	Check formatting; escape special characters; switch to HTML mode

Always check the

ok

field in the API response. If

ok

false

, display the

description

field to the user with guidance on how to fix the issue.

常见Telegram Bot API错误及解决方法：

错误	原因	解决方法
`401 Unauthorized`	机器人令牌无效	通过@BotFather重新生成令牌
`400 Bad Request: chat not found`	聊天ID错误或机器人不在聊天中	验证聊天ID；将机器人添加为频道管理员
`403 Forbidden: bot is not a member`	机器人已被移出频道	将机器人重新添加为频道管理员
`403 Forbidden: bot can't send messages`	机器人缺少发布权限	授予机器人“发布消息”的管理员权限
`429 Too Many Requests`	超出速率限制	等待响应中指定的 `retry_after` 秒数
`400 Bad Request: can't parse entities`	HTML/Markdown格式错误	检查格式；转义特殊字符；切换到HTML模式

请始终检查API响应中的

ok

字段。如果

ok

为

false

，请向用户显示

description

字段并提供解决问题的指导。

telegram-bot

Original

Translation

Telegram Bot Skill

Telegram Bot 营销技能指南

Prerequisites

前提条件

Environment Variables

环境变量

Creating a Bot via @BotFather

通过@BotFather创建机器人

Finding the Chat ID

查找聊天ID

Send a message in the channel/group first, then run:

先在频道/群组中发送一条消息，然后运行：

API Reference

API参考

sendMessage - Text Messages

sendMessage - 文本消息

sendPhoto - Images

sendPhoto - 图片

Send photo by URL

通过URL发送图片

Send photo from local file

发送本地图片

sendDocument - Files and Documents

sendDocument - 文件和文档

Send document by URL

通过URL发送文档

Send document from local file

发送本地文件

sendPoll - Polls and Quizzes

sendPoll - 投票和测验

Regular poll (multiple choice)

常规投票（多选）

Quiz mode (one correct answer)

测验模式（唯一正确答案）

Inline Keyboard Buttons (CTAs)

内联键盘按钮（CTA）

editMessageText - Edit Existing Messages

editMessageText - 编辑现有消息

deleteMessage - Delete a Message

deleteMessage - 删除消息

pinChatMessage - Pin Important Messages

pinChatMessage - 固定重要消息

Message Formatting

消息格式

HTML Mode (Recommended)

HTML模式（推荐）

MarkdownV2 Mode

MarkdownV2模式

Formatting Tips

格式设置技巧

Marketing Content Templates

营销内容模板

Template 1: Product Announcement

模板1：产品公告

Template 2: Blog Post Share

模板2：博客文章分享

Template 3: Community Update / Newsletter Digest

模板3：社区更新/新闻通讯摘要

Template 4: Product Launch with Image

模板4：带图片的产品发布

First, send the image with caption

先发送带说明的图片

Template 5: Engagement Poll

模板5：参与度投票

Template 6: Knowledge Quiz

模板6：知识测验

Template 7: Event / Webinar Announcement

模板7：活动/网络研讨会公告

Content Scheduling Workflow

内容调度工作流

Approach 1: Delayed Send with sleep (Simple)

方法1：使用sleep延迟发送（简单）

Send a message after a delay (e.g., 2 hours = 7200 seconds)

延迟一段时间后发送消息（例如：2小时=7200秒）

Approach 2: at Command (Specific Time)

方法2：at命令（特定时间）

Create the send script

Approach 1: Delayed Send with
`sleep`
(Simple)

方法1：使用
`sleep`
延迟发送（简单）

Approach 2:
`at`
Command (Specific Time)

方法2：
`at`
命令（特定时间）