mirror of
https://github.com/appleboy/telegram-action.git
synced 2026-10-09 04:30:43 +09:00
docs(readme): expand setup guide and input reference
- Add step-by-step bot setup: BotFather token, chat ID lookup for private chats, groups and channels, and repository secrets - Document comma-separated multiple recipients and glob support for media file inputs - Note that file-based inputs require actions/checkout - Add message formatting section warning about legacy Markdown escaping failures and recommending html for unpredictable content - Explain template variable usage with a rendered example and show the default message format - Add release and license badges, collapse the getUpdates JSON sample, cross-link all three language versions
This commit is contained in:
Bo-Yi Wu
+181
-64
@@ -1,94 +1,82 @@
|
||||
# 🚀 GitHub Actions 的 Telegram
|
||||
|
||||
[English](./README.md) | [繁體中文](./README.zh-tw.md)
|
||||
|
||||
[GitHub Action](https://github.com/features/actions) 用于发送 Telegram 通知消息。
|
||||
|
||||
|
||||
|
||||
[](https://github.com/appleboy/telegram-action/actions)
|
||||
[](https://github.com/appleboy/telegram-action/releases)
|
||||
[](./LICENSE)
|
||||
|
||||
## 使用方法
|
||||
|
||||
**注意**：如果您收到 "Error: Chat not found" 错误，请参考这个 stackoverflow 的回答 [这里](https://stackoverflow.com/a/41291666)。
|
||||
|
||||
发送自定义消息并查看如下的自定义变量。
|
||||
|
||||
## 输入变量
|
||||
|
||||
| 变量 | 描述 |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
|
||||
| to | **必填**。目标聊天的唯一标识符 |
|
||||
| token | **必填**。Telegram 授权令牌 |
|
||||
| socks5 | 可选。支持 socks5 代理 URL |
|
||||
| photo | 可选。照片消息 |
|
||||
| document | 可选。文档消息 |
|
||||
| sticker | 可选。贴纸消息 |
|
||||
| audio | 可选。音频消息 |
|
||||
| voice | 可选。语音消息 |
|
||||
| location | 可选。位置消息 |
|
||||
| venue | 可选。场馆消息 |
|
||||
| video | 可选。视频消息 |
|
||||
| debug | 可选。启用调试模式 |
|
||||
| format | 可选。`markdown` 或 `html`。参见 [MarkdownV2 样式](https://core.telegram.org/bots/api#markdownv2-style) |
|
||||
| message | 可选。自定义消息 |
|
||||
| message_file | 可选。用指定文件的内容覆盖默认消息模板。 |
|
||||
| message_thread_id | 可选。论坛目标消息串（主题）的唯一标识符，仅适用于论坛超级群组。 |
|
||||
| disable_web_page_preview | 可选。禁用此消息中链接的预览。默认值为 `false`。 |
|
||||
| disable_notification | 可选。禁用此消息的通知，支持发送无通知的消息。默认值为 `false`。 |
|
||||
|
||||
## 示例
|
||||
|
||||
发送照片消息：
|
||||
在每次 push 时发送自定义消息：
|
||||
|
||||
```yml
|
||||
- uses: actions/checkout@v7
|
||||
- name: send photo message
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message: send photo message
|
||||
photo: tests/github.png
|
||||
document: tests/gophercolor.png
|
||||
name: telegram message
|
||||
on: [push]
|
||||
jobs:
|
||||
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: send telegram message on push
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message: |
|
||||
${{ github.actor }} created commit:
|
||||
Commit message: ${{ github.event.commits[0].message }}
|
||||
|
||||
Repository: ${{ github.repository }}
|
||||
|
||||
See changes: https://github.com/${{ github.repository }}/commit/${{github.sha}}
|
||||
```
|
||||
|
||||
发送位置消息：
|
||||
移除 `message` 参数则发送默认消息，格式如下：
|
||||
|
||||
```yml
|
||||
- name: send location message
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
location: '24.9163213 121.1424972'
|
||||
venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
|
||||
```text
|
||||
appleboy/telegram-action/telegram message triggered by appleboy (push)
|
||||
```
|
||||
|
||||
使用自定义代理发送消息（支持 `http`、`https` 和 `socks5`），如 `socks5://127.0.0.1:1080` 或 `http://222.124.154.19:23500`
|
||||
|
||||
|
||||
```yml
|
||||
- name: send message using socks5 proxy URL
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
socks5: "http://222.124.154.19:23500"
|
||||
message: Send message from socks5 proxy URL.
|
||||
```
|
||||
> `@v1` 会跟踪 `v1.x` 的最新版本。如需完全可复现的构建，请锁定确切版本，
|
||||
> 例如 `appleboy/telegram-action@v1.1.1`。
|
||||
|
||||
## Secrets
|
||||
## 设置步骤
|
||||
|
||||
开始使用 [Telegram Bot API](https://core.telegram.org/bots/api)。
|
||||
### 1. 创建 Telegram bot
|
||||
|
||||
* `token`: Telegram 授权令牌。
|
||||
* `to`: 此聊天的唯一标识符。
|
||||
在 Telegram 中与 [@BotFather](https://t.me/BotFather) 对话，输入 `/newbot`
|
||||
并按提示操作。BotFather 会回复 bot token — 这就是 `TELEGRAM_TOKEN` secret。
|
||||
详见 [Telegram Bot API](https://core.telegram.org/bots/api)。
|
||||
|
||||
如何从 Telegram API 获取唯一标识符：
|
||||
### 2. 获取 chat ID
|
||||
|
||||
先给你的 bot 发送任意消息（群组或频道则需把 bot 添加为成员并在其中发一条
|
||||
消息），然后调用：
|
||||
|
||||
```bash
|
||||
curl https://api.telegram.org/bot<token>/getUpdates
|
||||
```
|
||||
|
||||
查看结果：（获取聊天 ID，如 `65382999`）
|
||||
从 `result[].message.chat.id` 读取 chat ID — 这就是 `TELEGRAM_TO` secret。
|
||||
|
||||
- **私聊**的 ID 是正数，例如 `65382999`。
|
||||
- **群组 / 超级群组 / 频道**的 ID 是负数，通常以 `-100` 开头，例如
|
||||
`-1001234567890`。请使用数字 ID，不支持 `@channelname` 这类用户名。
|
||||
- 如果 `getUpdates` 返回空结果，请在聊天中重新发一条消息后再调用一次。
|
||||
|
||||
**注意**：出现 "Error: Chat not found" 错误说明 chat ID 有误，或 bot 从未被
|
||||
添加到该聊天。也可参考这个 [StackOverflow 回答](https://stackoverflow.com/a/41291666)。
|
||||
|
||||
<details>
|
||||
<summary><code>getUpdates</code> 响应示例</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -121,8 +109,137 @@ curl https://api.telegram.org/bot<token>/getUpdates
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 3. 将 secrets 添加到仓库
|
||||
|
||||
进入仓库的 **Settings → Secrets and variables → Actions**，添加
|
||||
`TELEGRAM_TOKEN` 和 `TELEGRAM_TO`。
|
||||
|
||||
## 输入变量
|
||||
|
||||
| 变量 | 描述 |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
|
||||
| to | **必填**。目标聊天的 chat ID。用逗号分隔可发送到多个聊天，例如 `65382999,-1001234567890` |
|
||||
| token | **必填**。Telegram bot 授权 token |
|
||||
| message | 可选。自定义消息，留空则发送默认消息 |
|
||||
| message_file | 可选。用指定文件的内容覆盖默认消息模板，需搭配 `actions/checkout` |
|
||||
| message_thread_id | 可选。论坛目标消息串（主题）的唯一标识符，仅适用于论坛超级群组 |
|
||||
| format | 可选。`markdown` 或 `html`，留空为纯文本。参见下方[消息格式](#消息格式) |
|
||||
| photo | 可选。图片文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| document | 可选。文档文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| sticker | 可选。贴纸文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| audio | 可选。音频文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| voice | 可选。语音文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| video | 可选。视频文件路径，可逗号分隔多个并支持 glob 模式，需搭配 `actions/checkout` |
|
||||
| location | 可选。位置，格式为 `纬度 经度`，例如 `24.9163213 121.1424972` |
|
||||
| venue | 可选。地点，格式为 `纬度 经度 名称 地址` |
|
||||
| disable_web_page_preview | 可选。禁用此消息中链接的预览。默认值为 `false` |
|
||||
| disable_notification | 可选。静默发送消息（无通知提示音）。默认值为 `false` |
|
||||
| socks5 | 可选。自定义代理 URL（`http`、`https` 或 `socks5`） |
|
||||
| debug | 可选。启用调试模式。默认值为 `false` |
|
||||
|
||||
## 示例
|
||||
|
||||
发送图片和文档（文件类参数需搭配 `actions/checkout`，文件才会存在于
|
||||
workspace 中）：
|
||||
|
||||
```yml
|
||||
- uses: actions/checkout@v7
|
||||
- name: send photo message
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message: send photo message
|
||||
photo: tests/github.png
|
||||
document: tests/gophercolor.png
|
||||
```
|
||||
|
||||
从文件发送消息：
|
||||
|
||||
```yml
|
||||
- uses: actions/checkout@v7
|
||||
- name: send message file
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message_file: tests/message.txt
|
||||
```
|
||||
|
||||
将同一消息发送到多个聊天：
|
||||
|
||||
```yml
|
||||
- name: notify several chats
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: "65382999,-1001234567890"
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message: deploy finished
|
||||
```
|
||||
|
||||
发送位置消息：
|
||||
|
||||
```yml
|
||||
- name: send location message
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
location: '24.9163213 121.1424972'
|
||||
venue: '35.661777 139.704051 竹北體育館 新竹縣竹北市'
|
||||
```
|
||||
|
||||
发送消息到特定论坛主题（消息串）：
|
||||
|
||||
```yml
|
||||
- name: send message to forum topic
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message_thread_id: 42
|
||||
message: Hello from GitHub Actions!
|
||||
```
|
||||
|
||||
使用自定义代理发送消息（支持 `http`、`https` 和 `socks5`），如
|
||||
`socks5://127.0.0.1:1080` 或 `http://222.124.154.19:23500`：
|
||||
|
||||
```yml
|
||||
- name: send message using socks5 proxy URL
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
socks5: "http://222.124.154.19:23500"
|
||||
message: Send message from socks5 proxy URL.
|
||||
```
|
||||
|
||||
## 消息格式
|
||||
|
||||
使用 `format: markdown` 时，消息会以 Telegram 的传统
|
||||
[Markdown 样式](https://core.telegram.org/bots/api#markdown-style)发送。
|
||||
下划线会自动转义，但未成对的 `*`、`` ` `` 或 `[` 字符（例如出现在 commit
|
||||
消息中）会让 Telegram API 以 "can't parse entities" 错误拒绝整条消息。
|
||||
如果消息内容不可预期，建议改用 `format: html` 或纯文本（不设置 `format`）。
|
||||
|
||||
## 模板变量
|
||||
|
||||
`message` 和 `message_file` 参数会以模板方式渲染：`{{ ... }}` 占位符会被
|
||||
替换为环境中的对应值。
|
||||
|
||||
```yml
|
||||
- name: send message with template variables
|
||||
uses: appleboy/telegram-action@v1
|
||||
with:
|
||||
to: ${{ secrets.TELEGRAM_TO }}
|
||||
token: ${{ secrets.TELEGRAM_TOKEN }}
|
||||
message: |
|
||||
Commit {{ commit.sha }} on {{ commit.ref }}
|
||||
triggered by {{ repo.namespace }}
|
||||
```
|
||||
|
||||
| GitHub 变量 | Telegram 模板变量 |
|
||||
| ----------------- | ----------------- |
|
||||
| GITHUB_REPOSITORY | repo |
|
||||
|
||||
Reference in New Issue
Block a user