From 390cf7345777cd821dba28c72f436a78bce19cc5 Mon Sep 17 00:00:00 2001 From: Bo-Yi Wu Date: Sun, 16 Aug 2026 12:12:39 +0800 Subject: [PATCH] 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 --- README.md | 260 +++++++++++++++++++++++++++++++----------------- README.zh-cn.md | 245 +++++++++++++++++++++++++++++++++------------ README.zh-tw.md | 247 +++++++++++++++++++++++++++++++++------------ 3 files changed, 530 insertions(+), 222 deletions(-) diff --git a/README.md b/README.md index ca33c60..99a34bb 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,12 @@ ![notification](./images/telegram-notification.png) [![Actions Status](https://github.com/appleboy/telegram-action/workflows/telegram%20message/badge.svg)](https://github.com/appleboy/telegram-action/actions) +[![GitHub Release](https://img.shields.io/github/v/release/appleboy/telegram-action)](https://github.com/appleboy/telegram-action/releases) +[![License](https://img.shields.io/github/license/appleboy/telegram-action)](./LICENSE) ## Usage -**Note**: If you receive the "Error: Chat not found" error, please refer to this StackOverflow answer [here](https://stackoverflow.com/a/41291666). - -Send a custom message and view the custom variables below. +Send a custom message on every push: ```yml name: telegram message @@ -31,113 +31,57 @@ jobs: 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}} ``` -Remove the `message` input to send the default message. +Remove the `message` input to send the default message, which looks like: -```yml -- name: send default message - uses: appleboy/telegram-action@v1 - with: - to: ${{ secrets.TELEGRAM_TO }} - token: ${{ secrets.TELEGRAM_TOKEN }} +```text +appleboy/telegram-action/telegram message triggered by appleboy (push) ``` ![workflow](./images/telegram-workflow.png) -## Input variables +> `@v1` follows the latest `v1.x` release. Pin an exact version such as +> `appleboy/telegram-action@v1.1.1` if you want fully reproducible builds. -| Variable | Description | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| to | **required**. Unique identifier for the target chat. | -| token | **required**. Telegram authorization token. | -| socks5 | optional. Support socks5 proxy URL | -| photo | optional. Photo message | -| document | optional. Document message | -| sticker | optional. Sticker message | -| audio | optional. Audio message | -| voice | optional. Voice message | -| location | optional. Location message | -| venue | optional. Venue message | -| video | optional. Video message | -| debug | optional. Enable debug mode | -| format | optional. `markdown` or `html`. See [MarkdownV2 style](https://core.telegram.org/bots/api#markdownv2-style) | -| message | optional. Custom message | -| message_file | optional. Overwrite the default message template with the contents of the specified file. | -| message_thread_id | optional. Unique identifier for the target message thread (topic) of the forum; for forum supergroups only. | -| disable_web_page_preview | optional. Disables link previews for links in this message. Default is `false`. | -| disable_notification | optional. Disables notifications for this message, supports sending a message without notification. Default is `false`. | +## Setup -## Example +### 1. Create a Telegram bot -Send photo message: +Talk to [@BotFather](https://t.me/BotFather) in Telegram, send `/newbot`, and +follow the prompts. BotFather replies with the bot token — this is your +`TELEGRAM_TOKEN` secret. See the [Telegram Bot API](https://core.telegram.org/bots/api) +for details. -```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 -``` +### 2. Get the chat ID -Send location 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 竹北體育館 新竹縣竹北市' -``` - -Send a message to a specific forum topic (thread): - -```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! -``` - -Send message using custom proxy (support `http`, `https`, and `socks5`) like `socks5://127.0.0.1:1080` or `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. -``` - -## Secrets - -Getting started with [Telegram Bot API](https://core.telegram.org/bots/api). - -* `token`: Telegram authorization token. -* `to`: Unique identifier for this chat. - -How to get unique identifier from telegram api: +First send any message to your bot (for a group or channel, add the bot as a +member and post a message there), then call: ```bash curl https://api.telegram.org/bot/getUpdates ``` -See the result: (get chat id like `65382999`) +Read the chat ID from `result[].message.chat.id` — this is your `TELEGRAM_TO` +secret. + +- A **private chat** ID is a positive number, e.g. `65382999`. +- A **group / supergroup / channel** ID is negative and usually starts with + `-100`, e.g. `-1001234567890`. Use the numeric ID; usernames like + `@channelname` are not supported. +- If `getUpdates` returns an empty result, send a fresh message in the chat + and call it again. + +**Note**: the "Error: Chat not found" error means the chat ID is wrong or the +bot has never been added to that chat. See also this +[StackOverflow answer](https://stackoverflow.com/a/41291666). + +
+Example getUpdates response ```json { @@ -170,9 +114,139 @@ See the result: (get chat id like `65382999`) } ``` -## Template variable +
-| Github Variable | Telegram Template Variable | +### 3. Add the secrets to your repository + +In your repository go to **Settings → Secrets and variables → Actions** and +add `TELEGRAM_TOKEN` and `TELEGRAM_TO`. + +## Input variables + +| Variable | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| to | **required**. Chat ID of the target chat. Send to several chats with a comma-separated list, e.g. `65382999,-1001234567890`. | +| token | **required**. Telegram bot authorization token. | +| message | optional. Custom message. Falls back to the default message when empty. | +| message_file | optional. Overwrite the default message template with the contents of the specified file. Requires `actions/checkout`. | +| message_thread_id | optional. Unique identifier for the target message thread (topic) of the forum; for forum supergroups only. | +| format | optional. `markdown` or `html`. Plain text when empty. See [message formatting](#message-formatting) below. | +| photo | optional. Photo file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| document | optional. Document file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| sticker | optional. Sticker file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| audio | optional. Audio file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| voice | optional. Voice file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| video | optional. Video file path(s). Comma-separated list, glob patterns supported. Requires `actions/checkout`. | +| location | optional. Location as `latitude longitude`, e.g. `24.9163213 121.1424972`. | +| venue | optional. Venue as `latitude longitude title address`. | +| disable_web_page_preview | optional. Disables link previews for links in this message. Default is `false`. | +| disable_notification | optional. Sends the message silently, without a notification sound. Default is `false`. | +| socks5 | optional. Custom proxy URL (`http`, `https`, or `socks5`). | +| debug | optional. Enable debug mode. Default is `false`. | + +## Examples + +Send a photo and a document (file inputs need `actions/checkout` so the files +exist in the 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 +``` + +Send a message from a file: + +```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 +``` + +Send the same message to several chats: + +```yml +- name: notify several chats + uses: appleboy/telegram-action@v1 + with: + to: "65382999,-1001234567890" + token: ${{ secrets.TELEGRAM_TOKEN }} + message: deploy finished +``` + +Send a location 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 竹北體育館 新竹縣竹北市' +``` + +Send a message to a specific forum topic (thread): + +```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! +``` + +Send message using a custom proxy (supports `http`, `https`, and `socks5`), +like `socks5://127.0.0.1:1080` or `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. +``` + +## Message formatting + +With `format: markdown` the message is sent using Telegram's legacy +[Markdown style](https://core.telegram.org/bots/api#markdown-style). +Underscores are escaped automatically, but unbalanced `*`, `` ` ``, or `[` +characters (for example in a commit message) make the Telegram API reject the +whole message with a "can't parse entities" error. For messages with +unpredictable content, prefer `format: html` or plain text (no `format`). + +## Template variables + +The `message` and `message_file` inputs are rendered as templates: `{{ ... }}` +placeholders are replaced with values taken from the environment. + +```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 Variable | Telegram Template Variable | | ----------------- | -------------------------- | | GITHUB_REPOSITORY | repo | | GITHUB_ACTOR | repo.namespace | diff --git a/README.zh-cn.md b/README.zh-cn.md index d5b1c27..10c6cfe 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -1,94 +1,82 @@ # 🚀 GitHub Actions 的 Telegram +[English](./README.md) | [繁體中文](./README.zh-tw.md) + [GitHub Action](https://github.com/features/actions) 用于发送 Telegram 通知消息。 ![notification](./images/telegram-notification.png) [![Actions Status](https://github.com/appleboy/telegram-action/workflows/telegram%20message/badge.svg)](https://github.com/appleboy/telegram-action/actions) +[![GitHub Release](https://img.shields.io/github/v/release/appleboy/telegram-action)](https://github.com/appleboy/telegram-action/releases) +[![许可证](https://img.shields.io/github/license/appleboy/telegram-action)](./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` +![workflow](./images/telegram-workflow.png) -```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/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)。 + +
+getUpdates 响应示例 ```json { @@ -121,8 +109,137 @@ curl https://api.telegram.org/bot/getUpdates } ``` +
+ +### 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 | diff --git a/README.zh-tw.md b/README.zh-tw.md index e59fc90..db26fd5 100644 --- a/README.zh-tw.md +++ b/README.zh-tw.md @@ -1,94 +1,82 @@ # 🚀 Telegram 的 GitHub Actions +[English](./README.md) | [简体中文](./README.zh-cn.md) + 透過 [GitHub Action](https://github.com/features/actions) 發送 Telegram 通知訊息。 ![通知](./images/telegram-notification.png) [![Actions 狀態](https://github.com/appleboy/telegram-action/workflows/telegram%20message/badge.svg)](https://github.com/appleboy/telegram-action/actions) +[![GitHub Release](https://img.shields.io/github/v/release/appleboy/telegram-action)](https://github.com/appleboy/telegram-action/releases) +[![授權條款](https://img.shields.io/github/license/appleboy/telegram-action)](./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` +![workflow](./images/telegram-workflow.png) -```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/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)。 + +
+getUpdates 回應範例 ```json { @@ -121,9 +109,138 @@ curl https://api.telegram.org/bot/getUpdates } ``` +
+ +### 3. 將 secrets 加入 repository + +前往 repository 的 **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)發送。 +底線會自動 escape，但未成對的 `*`、`` ` `` 或 `[` 字元（例如出現在 commit +訊息中）會讓 Telegram API 以 "can't parse entities" 錯誤拒絕整則訊息。 +若訊息內容無法預期，建議改用 `format: html` 或純文字（不設定 `format`）。 + ## 模板變數 -| Github 變數 | Telegram 模板變數 | +`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 |