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
ci: add regression test for step output interpolation (#68 ) (#73 )
2026-10-03 01:30:44 +09:00 · 2026-08-16 12:12:39 +08:00 · 2026-08-16 11:27:58 +08:00 · 2026-08-16 10:58:37 +08:00 · 2026-08-16 10:57:44 +08:00 · 2026-08-16 10:57:44 +08:00
11 changed files with 661 additions and 234 deletions
@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(docker)"
@@ -1,18 +1,37 @@
 name: telegram message
-on: [push]
+on:
+  push:
+    branches:
+      - "**"
 jobs:
+  # Tests the working-tree Dockerfile and entrypoint.sh; the build job below
+  # runs against the published image referenced by action.yml instead.
+  local-image:
+    name: Test local image build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: build image from working tree
+        run: docker build -t telegram-action:local .
+
+      - name: send message via local image
+        env:
+          TELEGRAM_TO: ${{ secrets.TELEGRAM_TO }}
+          TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
+        run: |
+          docker run --rm \
+            -e INPUT_TO="$TELEGRAM_TO" \
+            -e INPUT_TOKEN="$TELEGRAM_TOKEN" \
+            -e INPUT_MESSAGE_THREAD_ID= \
+            -e INPUT_MESSAGE="ci: local image smoke test for ${{ github.sha }}" \
+            telegram-action:local
+
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
-      - name: send custom message with args
-        uses: ./
-        with:
-          to: ${{ secrets.TELEGRAM_TO }}
-          token: ${{ secrets.TELEGRAM_TOKEN }}
-          args: The ${{ github.event_name }} event triggered first step.
-
      - name: send message using with
        uses: ./
        with:
@@ -65,6 +84,28 @@ jobs:
          token: ${{ secrets.TELEGRAM_TOKEN }}
          message_file: tests/message.txt

+      # Regression test for issue #68: step outputs written to $GITHUB_OUTPUT
+      # must be usable inside the message input. The step producing the
+      # output needs an `id` so it can be referenced via steps.<id>.outputs.
+      - name: set step output
+        id: repo-discussion
+        run: |
+          COUNT=42
+          echo "discussionCount=$COUNT" >> "$GITHUB_OUTPUT"
+
+      - name: verify step output is interpolated
+        run: |
+          test "${{ steps.repo-discussion.outputs.discussionCount }}" = "42"
+
+      - name: send message with step output (issue #68)
+        uses: ./
+        with:
+          to: ${{ secrets.TELEGRAM_TO }}
+          token: ${{ secrets.TELEGRAM_TOKEN }}
+          message: |
+            There are currently ${{ steps.repo-discussion.outputs.discussionCount }} discussions, come on!
+          format: markdown
+
      # - name: send message using socks5 proxy URL
      #   uses: appleboy/telegram-action@master
      #   with:
@@ -0,0 +1,59 @@
+name: Docker Image
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      # full semver only; the floating major tag (v1) must not trigger builds
+      - "v[0-9]*.[0-9]*.[0-9]*"
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker meta
+        id: docker-meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.docker-meta.outputs.tags }}
+          labels: ${{ steps.docker-meta.outputs.labels }}
@@ -3,7 +3,8 @@ name: Goreleaser
 on:
  push:
    tags:
-      - "*"
+      # full semver only; the floating major tag (v1) must not cut a release
+      - "v[0-9]*.[0-9]*.[0-9]*"

 permissions:
  contents: write
@@ -17,11 +18,6 @@ jobs:
        with:
          fetch-depth: 0

-      - name: Setup go
-        uses: actions/setup-go@v7
-        with:
-          go-version: "^1"
-
      - name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
@@ -0,0 +1 @@
+.DS_Store
@@ -1,7 +1,6 @@
-FROM ghcr.io/appleboy/drone-telegram:1.4.2
+FROM ghcr.io/appleboy/drone-telegram:1.5.1

 COPY entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh

 WORKDIR /github/workspace

@@ -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
@@ -24,118 +24,64 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: send telegram message on push
-        uses: appleboy/telegram-action@master
+        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}}
 ```

-Remove `args` 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@master
-  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                                                                                                             |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| 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@master
- name: send photo message
-  uses: appleboy/telegram-action@master
-  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@master
-  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@master
-  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@master
-  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<token>/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).
+
+<details>
+<summary>Example <code>getUpdates</code> response</summary>

 ```json
 {
@@ -168,9 +114,139 @@ See the result: (get chat id like `65382999`)
 }
 ```

-## Template variable
+</details>

-| 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             |
@@ -1,91 +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)。
-
-发送自定义消息并查看如下的自定义变量。
-
-## 输入变量
-
-| 变量                     | 描述                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------- |
-| 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             | 可选。用指定文件的内容覆盖默认消息模板。                                                                |
-| disable_web_page_preview | 可选。禁用此消息中链接的预览。默认值为 `false`。                                                        |
-| disable_notification     | 可选。禁用此消息的通知，支持发送无通知的消息。默认值为 `false`。                                        |
-
-## 示例
-
-发送照片消息：
+在每次 push 时发送自定义消息：

 ```yml
- uses: actions/checkout@master
- name: send photo message
-  uses: appleboy/telegram-action@master
-  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@master
-  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@master
-  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
 {
@@ -118,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              |
@@ -1,91 +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)。
-
-發送自訂訊息並參考以下自訂變數。
-
-## 輸入變數
-
-| 變數                     | 說明                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------- |
-| 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             | 選填。使用指定檔案的內容覆蓋預設訊息模板                                                                |
-| disable_web_page_preview | 選填。停用此訊息中連結的預覽。預設為 `false`                                                            |
-| disable_notification     | 選填。停用此訊息的通知，支援發送無通知的訊息。預設為 `false`                                            |
-
-## 範例
-
-發送圖片訊息：
+在每次 push 時發送自訂訊息：

 ```yml
- uses: actions/checkout@master
- name: send photo message
-  uses: appleboy/telegram-action@master
-  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@master
-  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@master
-  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
 {
@@ -118,9 +109,138 @@ curl https://api.telegram.org/bot<token>/getUpdates
 }
 ```

+</details>
+
+### 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    |
@@ -4,8 +4,10 @@ author: 'Bo-Yi Wu'
 inputs:
  to:
    description: 'telegram user'
+    required: true
  token:
    description: 'telegram token'
+    required: true
  message:
    description: 'telegram message'
  message_file:
@@ -40,7 +42,7 @@ inputs:
    description: 'unique identifier for the target message thread (topic) of the forum; for forum supergroups only'
 runs:
  using: 'docker'
-  image: 'Dockerfile'
+  image: 'docker://ghcr.io/appleboy/telegram-action:1.1.1'

 branding:
  icon: 'message-square'
@@ -4,6 +4,4 @@ set -eu

 export GITHUB="true"

-[ -n "$*" ] && export TELEGRAM_MESSAGE="$*"
-
 /bin/drone-telegram
Author	SHA1	Message	Date
Bo-Yi Wu	390cf73457	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	2026-08-16 12:12:39 +08:00
Bo-Yi Wu GitHub Claude Fable 5	a2d0caf64a	ci: add regression test for step output interpolation (#68 ) (#73 ) Reproduce the exact scenario from issue #68: write a value to $GITHUB_OUTPUT in a step with an id, assert the runner interpolates it, then send it through the message input with format: markdown. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-08-16 11:27:58 +08:00
Bo-Yi Wu	978281de94	ci: run message tests on branch pushes only - Tag pushes re-ran the whole suite and sent duplicate telegram messages on every release	2026-08-16 10:58:37 +08:00
Bo-Yi Wu	dd9f2d9fa7	docs(readme): reference the floating v1 tag in examples	2026-08-16 10:57:44 +08:00
Bo-Yi Wu	4023d256c8	ci: restrict tag triggers to full semver - Prevent the floating v1 major tag from cutting a goreleaser release or a docker image build	2026-08-16 10:57:44 +08:00
Bo-Yi Wu	214f06cfa3	chore(release): pin action image and docs to 1.1.1	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	2608c6db39	fix(entrypoint): drop empty thread id workaround - drone-telegram 1.5.1 handles empty INPUT_MESSAGE_THREAD_ID itself	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	c078210187	chore(docker): bump drone-telegram base image to 1.5.1 - Upstream now treats empty numeric env vars as unset	2026-08-16 10:54:18 +08:00
Bo-Yi Wu	7f612b977e	chore: ignore .DS_Store files	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	c18c95644a	docs(readme): pin examples to v1.1.0 and sync input tables - Replace mutable @master references with the v1.1.0 tag - Add required to/token rows to all input tables - Add missing message_thread_id row to both Chinese translations - Reword the default-message note to reference message instead of the removed args mechanism	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	6753faf1d2	feat(action): mark to and token inputs as required - Surface missing credentials before the container runs	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	53d62f6c74	ci: add working-tree image test and drop dead args step - Build and smoke-test the local Dockerfile/entrypoint since the action now runs the published ghcr image instead of the working tree - Exercise the empty INPUT_MESSAGE_THREAD_ID guard in the smoke test - Remove the args step which silently sent the default message	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	e9e9d8fda7	fix(entrypoint): remove dead args passthrough - Container args were never wired up in action.yml (no runs.args), so the positional-argument branch could never fire	2026-08-16 10:33:52 +08:00
Bo-Yi Wu	16657635b3	fix(action): pin prebuilt image to versioned tag - Replace the mutable latest tag with the immutable 1.1.0 image tag so released action versions stay reproducible and a bad master push cannot break existing users	2026-08-16 10:27:42 +08:00
Bo-Yi Wu	fd541f19b0	fix(entrypoint): unset empty INPUT_MESSAGE_THREAD_ID - The runner exports every declared input as an env var even when unset, and drone-telegram 1.5.0 fails to parse an empty string for the integer message.thread.id flag	2026-08-16 10:13:31 +08:00
Bo-Yi Wu	f8121d9e5a	perf(action): use prebuilt ghcr image instead of building Dockerfile - Pull ghcr.io/appleboy/telegram-action:latest at runtime instead of building the Docker image on every workflow run	2026-08-16 10:11:41 +08:00
Bo-Yi Wu	b8da483c2e	ci(goreleaser): remove unused Go setup step - goreleaser config skips builds, so the Go toolchain is never used	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	724a55ccf8	chore(docker): drop redundant chmod layer - entrypoint.sh already carries the executable bit in git	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	8223320a4c	chore(deps): add dependabot config for actions and docker - Enable weekly update checks for GitHub Actions and the Dockerfile base image	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	ea12760348	ci(docker): publish prebuilt image to ghcr - Build and push multi-arch (amd64/arm64) image on master pushes and version tags - Generate latest and semver tags via docker metadata action - Build without pushing on pull requests for validation	2026-08-16 10:10:14 +08:00
Bo-Yi Wu	d678193671	chore(docker): bump drone-telegram base image to 1.5.0 - Upgrade the base image from 1.4.2 to 1.5.0	2026-08-16 10:00:47 +08:00