Back to Details

telegram-bot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Call the official Telegram Bot API with 
curl + jq
. The bot token is injected as 
$TELEGRAMBOT_BOT_TOKEN
; an optional default target chat is 
$TELEGRAMBOT_CHAT_ID
(e.g. 
@your_channel
or a numeric id). Base URL: 
https://api.telegram.org/bot$TELEGRAMBOT_BOT_TOKEN/<METHOD>
.
Every response is JSON 
{"ok":true,"result":...}
on success, or 
{"ok":false,"error_code":<n>,"description":"<msg>"}
on failure — always check 
.ok
and show 
description
verbatim. Common failures: 
401 Unauthorized
= bad/ revoked token (reconnect the connector), 
400 Bad Request: chat not found
= wrong chat_id, 
403 Forbidden: bot is not a member of the channel chat
/ 
... need administrator rights
= add the bot to the channel as an admin with post rights, 
429
with 
parameters.retry_after
= rate-limited, wait that many seconds.
chat_id
is 
@channelusername
(public) or the numeric id (private channels/ groups, often negative like 
-1001234567890
). Resolve/verify it with 
getChat
.
使用
curl + jq
调用官方Telegram Bot API。机器人令牌会被注入为
$TELEGRAMBOT_BOT_TOKEN
；可选的默认目标聊天为
$TELEGRAMBOT_CHAT_ID
（例如
@your_channel
或数字ID）。基础URL：
https://api.telegram.org/bot$TELEGRAMBOT_BOT_TOKEN/<METHOD>
。
成功时，每个响应都是JSON格式的
{"ok":true,"result":...}
；失败时则为
{"ok":false,"error_code":<n>,"description":"<msg>"}
——务必检查
.ok
字段，并原样显示
description
内容。常见失败情况：
401 Unauthorized
= 令牌无效/已撤销（重新连接连接器），
400 Bad Request: chat not found
= chat_id错误，
403 Forbidden: bot is not a member of the channel chat
/ 
... need administrator rights
= 将机器人添加为频道管理员并赋予发帖权限，
429
伴随 
parameters.retry_after
= 触发速率限制，等待指定秒数后重试。
chat_id
可以是
@channelusername
（公开频道）或数字ID（私有频道/群组，通常为负数，例如
-1001234567890
）。可通过
getChat
方法解析/验证该ID。

Step 1 — verify the bot + target

步骤1 — 验证机器人与目标聊天

bash
BOT="https://api.telegram.org/bot$TELEGRAMBOT_BOT_TOKEN"
curl -sS "$BOT/getMe" | jq '{ok, bot: .result.username, name: .result.first_name}'
bash
BOT="https://api.telegram.org/bot$TELEGRAMBOT_BOT_TOKEN"
curl -sS "$BOT/getMe" | jq '{ok, bot: .result.username, name: .result.first_name}'

confirm the bot can post to the target chat (must be admin in the channel):

确认机器人可向目标聊天发帖（必须是频道管理员）：

CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}" curl -sS -G "$BOT/getChat" --data-urlencode "chat_id=$CHAT"
| jq '{ok, type: .result.type, title: .result.title, error: .description}'
undefined
CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}" curl -sS -G "$BOT/getChat" --data-urlencode "chat_id=$CHAT"
| jq '{ok, type: .result.type, title: .result.title, error: .description}'
undefined

Send a text post

发送文本帖子

Confirm the text and target chat with the user before posting publicly. Text is 1-4096 chars. Use 
parse_mode=HTML
(simplest) or 
MarkdownV2
.
bash
CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}"
curl -sS -G "$BOT/sendMessage" \
  --data-urlencode "chat_id=$CHAT" \
  --data-urlencode "text=<b>Hello</b> from the bot 👋  #ai" \
  --data-urlencode "parse_mode=HTML" \
  --data-urlencode "disable_web_page_preview=false" \
  | jq '{ok, message_id: .result.message_id, error: .description}'
The public post URL for a channel is 
https://t.me/<channelusername>/<message_id>
.
  • HTML mode supports 
    <b> <i> <u> <s> <a href> <code> <pre> <blockquote>
    . Escape literal 
    < > &
    as 
    &lt; &gt; &amp;
    .
  • MarkdownV2 requires escaping 
    _ * [ ] ( ) ~ \
    > # + - = | { } . !
    with
    `.
  • Always send 
    text
    via 
    --data-urlencode
    so newlines/Cyrillic/emoji aren't mangled.
公开发帖前请与用户确认文本内容和目标聊天。 文本长度为1-4096字符。可使用
parse_mode=HTML
（最简单）或
MarkdownV2
。
bash
CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}"
curl -sS -G "$BOT/sendMessage" \
  --data-urlencode "chat_id=$CHAT" \
  --data-urlencode "text=<b>Hello</b> from the bot 👋  #ai" \
  --data-urlencode "parse_mode=HTML" \
  --data-urlencode "disable_web_page_preview=false" \
  | jq '{ok, message_id: .result.message_id, error: .description}'
频道公开帖子的URL为
https://t.me/<channelusername>/<message_id>
。
  • HTML模式支持
    <b> <i> <u> <s> <a href> <code> <pre> <blockquote>
    标签。需将字面量
    < > &
    转义为
    &lt; &gt; &amp;
    。
  • MarkdownV2模式需要使用
    \
    转义
    _ * [ ] ( ) ~ \
    > # + - = | { } . !`这些字符。
  • 务必通过
    --data-urlencode
    发送
    text
    参数，避免换行符、西里尔字母或表情符号出现乱码。

Send a photo with caption

发送带说明文字的图片

bash
CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}"
curl -sS -G "$BOT/sendPhoto" \
  --data-urlencode "chat_id=$CHAT" \
  --data-urlencode "photo=https://cdn.example.com/pic.jpg" \
  --data-urlencode "caption=<b>Caption</b> text" \
  --data-urlencode "parse_mode=HTML" \
  | jq '{ok, message_id: .result.message_id, error: .description}'
photo
accepts an HTTPS URL (≤5 MB, Telegram fetches it), a Telegram 
file_id
, or an uploaded file. Caption is 0-1024 chars. For an album use 
sendMediaGroup
.
bash
CHAT="${TELEGRAMBOT_CHAT_ID:-@your_channel}"
curl -sS -G "$BOT/sendPhoto" \
  --data-urlencode "chat_id=$CHAT" \
  --data-urlencode "photo=https://cdn.example.com/pic.jpg" \
  --data-urlencode "caption=<b>Caption</b> text" \
  --data-urlencode "parse_mode=HTML" \
  | jq '{ok, message_id: .result.message_id, error: .description}'
photo
参数支持HTTPS URL（≤5MB，由Telegram获取）、Telegram的
file_id
，或上传的文件。说明文字长度为0-1024字符。如需发送相册，请使用
sendMediaGroup
方法。

Edit / delete a message

编辑/删除消息

bash
undefined
bash
undefined

edit text (same chat_id + message_id)

编辑文本（需相同的chat_id + message_id）

curl -sS -G "$BOT/editMessageText"
--data-urlencode "chat_id=$CHAT" --data-urlencode "message_id=123"
--data-urlencode "text=Updated text" --data-urlencode "parse_mode=HTML"
| jq '{ok, error: .description}'
curl -sS -G "$BOT/editMessageText"
--data-urlencode "chat_id=$CHAT" --data-urlencode "message_id=123"
--data-urlencode "text=Updated text" --data-urlencode "parse_mode=HTML"
| jq '{ok, error: .description}'

delete a message

删除消息

curl -sS -G "$BOT/deleteMessage"
--data-urlencode "chat_id=$CHAT" --data-urlencode "message_id=123"
| jq '{ok, error: .description}'

`deleteMessage` works for the bot's own channel posts within 48 hours (and needs
`can_delete_messages`/post rights).
curl -sS -G "$BOT/deleteMessage"
--data-urlencode "chat_id=$CHAT" --data-urlencode "message_id=123"
| jq '{ok, error: .description}'

`deleteMessage`方法仅能在48小时内删除机器人自身发布的频道帖子（且需要`can_delete_messages`权限或发帖权限）。

Gotchas

注意事项

  • The bot must be added to the channel/group as an admin with post rights, or sends return 
    403
    . 
    getChat
    first to confirm access.
  • Channel numeric ids are large negative numbers (
    -100...
    ); prefer 
    @username
    for public channels.
  • Free broadcast limit is ~30 msg/s; space out bulk sends or you'll hit 
    429
    (respect 
    parameters.retry_after
    ).
  • This is the bot speaking (not your personal account) — for reading your own DMs / groups as yourself, use the 
    telegram
    (MTProto) connector instead.
  • 必须将机器人添加为频道/群组的管理员并赋予发帖权限，否则发送请求会返回
    403
    错误。请先使用
    getChat
    方法确认访问权限。
  • 频道的数字ID为大负数（
    -100...
    ）；公开频道优先使用
    @username
    。
  • 免费广播限制约为30条/秒；批量发送时请间隔一段时间，否则会触发
    429
    错误（请遵循
    parameters.retry_after
    指定的等待时间）。
  • 此操作是机器人执行的（而非你的个人账号）——如果需要以个人身份读取自己的私信/群组消息，请使用
    telegram
    （MTProto）连接器。