actions/telegram-action
1
0
Fork 0
mirror of https://github.com/appleboy/telegram-action.git synced 2026-10-10 13:10:42 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): expand setup guide and input reference

Browse Source 
- 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
2026-08-16 12:12:39 +08:00
parent a2d0caf64a
commit 390cf73457
3 changed files with 530 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+167 -93
View File
@@ -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<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
{
@@ -170,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 |