mirror of
https://github.com/appleboy/telegram-action.git
synced 2026-10-04 10:10:43 +09:00
Bo-Yi Wu
390cf73457
- 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
254 lines
9.7 KiB
Markdown
254 lines
9.7 KiB
Markdown
# 🚀 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)
|
||
|
||
## 使用方法
|
||
|
||
在每次 push 时发送自定义消息：
|
||
|
||
```yml
|
||
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` 参数则发送默认消息，格式如下：
|
||
|
||
```text
|
||
appleboy/telegram-action/telegram message triggered by appleboy (push)
|
||
```
|
||
|
||
|
||
|
||
> `@v1` 会跟踪 `v1.x` 的最新版本。如需完全可复现的构建，请锁定确切版本，
|
||
> 例如 `appleboy/telegram-action@v1.1.1`。
|
||
|
||
## 设置步骤
|
||
|
||
### 1. 创建 Telegram bot
|
||
|
||
在 Telegram 中与 [@BotFather](https://t.me/BotFather) 对话，输入 `/newbot`
|
||
并按提示操作。BotFather 会回复 bot token — 这就是 `TELEGRAM_TOKEN` secret。
|
||
详见 [Telegram Bot API](https://core.telegram.org/bots/api)。
|
||
|
||
### 2. 获取 chat ID
|
||
|
||
先给你的 bot 发送任意消息（群组或频道则需把 bot 添加为成员并在其中发一条
|
||
消息），然后调用：
|
||
|
||
```bash
|
||
curl https://api.telegram.org/bot<token>/getUpdates
|
||
```
|
||
|
||
从 `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
|
||
{
|
||
"ok": true,
|
||
"result": [
|
||
{
|
||
"update_id": 664568113,
|
||
"message": {
|
||
"message_id": 8423,
|
||
"from": {
|
||
"id": 65382999,
|
||
"is_bot": false,
|
||
"first_name": "Bo-Yi",
|
||
"last_name": "Wu (appleboy)",
|
||
"username": "appleboy46",
|
||
"language_code": "en"
|
||
},
|
||
"chat": {
|
||
"id": 65382999,
|
||
"first_name": "Bo-Yi",
|
||
"last_name": "Wu (appleboy)",
|
||
"username": "appleboy46",
|
||
"type": "private"
|
||
},
|
||
"date": 1550333434,
|
||
"text": "?"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
</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 |
|
||
| GITHUB_ACTOR | repo.namespace |
|
||
| GITHUB_SHA | commit.sha |
|
||
| GITHUB_REF | commit.ref |
|
||
| GITHUB_WORKFLOW | github.workflow |
|
||
| GITHUB_ACTION | github.action |
|
||
| GITHUB_EVENT_NAME | github.event.name |
|
||
| GITHUB_EVENT_PATH | github.event.path |
|
||
| GITHUB_WORKSPACE | github.workspace |
|