Bỏ qua, đến phần nội dung

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 ph trê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-telegram của Tara. Bạn dùng chúng dưới dạng kit-notify-telegram@<version>:<sha256>.

1. Tạo bot ​

  1. Trong Telegram, tìm @BotFather và mở cuộc trò chuyện với tài khoản có dấu xác minh. Gửi /newbot.
  2. BotFather hỏi tên. Bạn nhập tên hiển thị tùy ý, ví dụ PhillipCLI Alerts.
  3. 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.
  4. 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.
Hình minh họa, màn hình thật có thể hơi khác. Sau khi gửi /newbot, đặt tên và username kết thúc bằng bot, BotFather trả về token (1).

2. Thêm bot vào nhóm ​

  1. Mở nhóm của bạn rồi chạm vào tên nhóm để xem thông tin nhóm.
  2. Chọn Add Members, tìm username của bot, chọn bot rồi xác nhận.
  3. 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.
Trong thông tin nhóm, chọn Add Members (1), chọn bot (2), rồi gửi /start@<username của bot> vào nhóm (3).

3. Lấy chat ID ​

  1. 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.
  2. Tìm đối tượng chứa tin /start của bạn và đọc message.chat.id.
  3. 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.
  4. 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.
Trong kết quả getUpdates, giá trị id nằm trong message.chat chính là chatId (1), ví dụ -1001234567890.

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.

bash
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ọi check(): hỏi Telegram về bot (getMe) và nhóm (getChat), không gửi gì. Kết quả có dạng bot @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.

bash
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ụKitSettings mặc địnhBí mật
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_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.

  1. Đă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.
  2. Chọn Organization và Plugin là kit-notify-telegram.
  3. Trong Organization-specific settings, nhập mỗi dòng một cặp name=value, ví dụ chatId=-1001234567890.
  4. Chọn các sự kiện muốn nhận rồi lưu.
  5. Ở 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.
Nhập chatId=… vào Organization-specific settings (1), chọn sự kiện (2), rồi bấm Save (3). Gửi thử bằng menu thao tác ở dòng của kênh.

Bạn cũng làm được việc này bằng dòng lệnh:

bash
ph tara notify set <org> kit-notify-telegram --set chatId=<chat id> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-telegram

Xử lý lỗi ​

Nội dung lỗiNguyên nhânCách sửa
the Telegram bot token is missingBiế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 missingSettings chưa có chatIdThê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ựcChé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 supergroupThêm bot, đọc lại ID bằng getUpdates, tìm migrate_to_chat_id
could not reach TelegramMáy chủ không gọi tới được api.telegram.orgMở đườ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ỗiChờ. 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.

Đọc thêm ​