Cài thông báo Telegram
Hướng dẫn này nối kit kit-notify-telegram vào một nhóm Telegram. Xong rồi, Tara, Ryoma hoặc Bandum sẽ đăng cảnh báo và sự kiện duyệt bài vào nhóm đó. Bạn mất chừng mười phút.
Về các hình
Các hình là hình minh họa, chỉ cho bạn thấy cần bấm vào đâu. Telegram, Slack và Portal thỉnh thoảng đổi giao diện nên màn hình thật có thể hơi khác. Tên nút thì không đổi.
Dành cho ai
- Quản trị viên cài kit thông báo lên máy chủ (xem Thông báo).
- Owner hoặc admin của tổ chức muốn nhận cảnh báo trong nhóm của đội.
Trước khi bắt đầu
- Một tài khoản Telegram và một nhóm sẽ nhận cảnh báo. Bạn phải có quyền thêm thành viên vào nhóm đó.
- Lệnh
phtrên máy của bạn, để thử kit trước khi đụng vào máy chủ. - Version và sha256 của kit trên trang tài nguyên
kit-notify-telegramcủa Tara. Bạn dùng chúng dưới dạngkit-notify-telegram@<version>:<sha256>.
1. Tạo bot
- Trong Telegram, tìm
@BotFathervà mở cuộc trò chuyện với tài khoản có dấu xác minh. Gửi/newbot. - BotFather hỏi tên. Bạn nhập tên hiển thị tùy ý, ví dụ
PhillipCLI Alerts. - BotFather hỏi username. Username không được trùng và phải kết thúc bằng
bot, ví dụphillipcli_alerts_bot. - BotFather trả lời bằng một tin nhắn có token, dạng
123456789:AA…. Bạn chép token và giữ bí mật. Ai có token đều gửi tin nhắn được nhân danh bot của bạn.
2. Thêm bot vào nhóm
- Mở nhóm của bạn rồi chạm vào tên nhóm để xem thông tin nhóm.
- Chọn Add Members, tìm username của bot, chọn bot rồi xác nhận.
- Bot mặc định bật chế độ riêng tư, nên trong nhóm nó chỉ thấy lệnh và lời nhắc tên. Bạn gửi
/start@<bot_username>trong nhóm (thay<bot_username>bằng username bot của bạn) để bot nhận được một tin nhắn.
3. Lấy chat ID
- Mở địa chỉ sau trong trình duyệt, thay
<token>bằng token của bạn:https://api.telegram.org/bot<token>/getUpdates. - Tìm đối tượng chứa tin
/startcủa bạn và đọcmessage.chat.id. - Chép con số, kể cả dấu trừ. ID của supergroup có dạng
-100…. ID của nhóm thường là số âm không có-100. - Xóa trang này khỏi lịch sử trình duyệt, và đừng dùng trình duyệt dùng chung. Địa chỉ có chứa token.
Khi nhóm được nâng cấp
Khi Telegram nâng nhóm thường lên supergroup, ID đổi. Lúc đó getUpdates hiện migrate_to_chat_id. Bạn cập nhật chatId sang giá trị mới.
Muốn đăng vào kênh (channel) thay vì nhóm, bạn thêm bot làm quản trị viên của kênh. Bot chỉ là thành viên thì không đăng được.
4. Thử kit bằng ph kit check
Bạn đưa token qua biến PHILLIP_KIT_TOKEN, không bao giờ đưa qua tham số. Lệnh ph kit check nhận thư mục kit hoặc tên[@version], các --set key=value (lặp được), --live và --send <text> kèm --to tùy chọn.
PHILLIP_KIT_TOKEN=<bot token> ph kit check kit-notify-telegram --set chatId=<chat id> --send "test"- Không thêm tùy chọn nào thì lệnh kiểm hợp đồng và setting bắt buộc.
- Có
--live, lệnh gọicheck(): hỏi Telegram về bot (getMe) và nhóm (getChat), không gửi gì. Kết quả có dạngbot @your_bot → Tên nhóm. - Có
--send, lệnh đăng một tin thật vào nhóm.
5. Cấu hình dịch vụ
Tara, Ryoma và Bandum dùng chung một kit. Mỗi dịch vụ có tiền tố biến riêng. Ví dụ dưới đây là cho Ryoma. Bạn lấy <version> và <sha256> trên trang tài nguyên của Tara.
RYOMA_NOTIFY_PLUGINS=kit-notify-telegram@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM=<bot token>
RYOMA_NOTIFY_SETTINGS={"kit-notify-telegram":{"chatId":"<chat id>"}}| Dịch vụ | Kit | Settings mặc định | Bí mật |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
Tara còn cần TARA_NOTIFY_TOKEN, token Tara chỉ đọc để tải gói kit. Đổi biến xong, bạn khởi động lại dịch vụ. Các biến còn lại có trong trang Thông báo.
6. Chọn kênh cho từng tổ chức
Tara gửi sự kiện của mỗi tổ chức vào nhóm riêng của tổ chức đó. Bí mật chỉ có một cho mỗi kit trên máy chủ, còn mỗi tổ chức tự đặt chatId của mình.
- Đăng nhập Portal bằng tài khoản owner hoặc admin của tổ chức. Mở menu tài khoản, chọn Admin, rồi Notifications, rồi thêm một kênh.
- Chọn Organization và Plugin là
kit-notify-telegram. - Trong Organization-specific settings, nhập mỗi dòng một cặp
name=value, ví dụchatId=-1001234567890. - Chọn các sự kiện muốn nhận rồi lưu.
- Ở menu thao tác của dòng, chọn Send test. Tin nhắn sẽ tới nhóm trong vài giây.
Bạn cũng làm được việc này bằng dòng lệnh:
ph tara notify set <org> kit-notify-telegram --set chatId=<chat id> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-telegramXử lý lỗi
| Nội dung lỗi | Nguyên nhân | Cách sửa |
|---|---|---|
the Telegram bot token is missing | Biến bí mật trống hoặc đặt sai tên | Đặt <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM rồi khởi động lại |
settings.chatId (ID of the chat group that receives notifications) is missing | Settings chưa có chatId | Thêm chatId vào settings của dịch vụ hoặc của kênh tổ chức |
Telegram rejected the bot token: … | Token sai, thừa dấu cách hoặc không còn hiệu lực | Chép lại token từ tin nhắn của BotFather |
chat group <id> not found: … (was the bot added to the group?) | ID sai, bot chưa vào nhóm, hoặc nhóm đã lên supergroup | Thêm bot, đọc lại ID bằng getUpdates, tìm migrate_to_chat_id |
could not reach Telegram | Máy chủ không gọi tới được api.telegram.org | Mở đường mạng, hoặc đặt apiUrl về proxy nội bộ |
Telegram is temporarily failing (HTTP 429) hoặc (HTTP 5xx) | Telegram giới hạn tốc độ hoặc đang lỗi | Chờ. Tara thử lại tối đa 8 lần |
Telegram returned HTTP …: … | Bị từ chối vì lý do khác, ví dụ bot bị đuổi khỏi nhóm hoặc chưa là quản trị viên của kênh | Đọc phần sau dấu hai chấm và sửa quyền của bot |
Giới hạn
- Mỗi cấu hình chỉ có một đích: một chat ID.
- Tin nhắn bị cắt ở 4096 ký tự. Tiêu đề nằm ở dòng đầu.
- Kit bỏ qua địa chỉ
to, vì ở đây Telegram không có người nhận riêng. - Tin chỉ chứa siêu dữ liệu và liên kết, không bao giờ có nội dung công việc.