Tổng quan

Người dùng gửi tin nhắn
        |
        v
Telegram Bot API
        |
        | HTTPS POST webhook
        v
EzyOA
        |
        | Xử lý hội thoại / phản hồi
        v
Telegram Bot API
        |
        v
Người dùng nhận tin nhắn

• Bot Token để gửi tin nhắn và truy vấn thông tin chat qua Telegram Bot API.
• Webhook Secret Token để xác thực request webhook gửi từ Telegram.
• Webhook URL để nhận tin nhắn và sự kiện thay đổi trạng thái của bot.

Chuẩn bị

• Một hệ thống EzyOA đang hoạt động.
• Domain công khai có HTTPS hợp lệ.
• Quyền truy cập trang quản trị EzyOA.
• Tài khoản Telegram để tạo bot.
• web url của EzyOA đã được cấu hình đúng theo domain công khai.

https://oa.example.com

Tạo Telegram Bot

/newbot

1. Nhập tên hiển thị của bot.
2. Nhập username cho bot.
3. Username thường phải kết thúc bằng bot, ví dụ:

ezyoa_support_bot

123456789:AAExampleTelegramBotToken

curl "https://api.telegram.org/bot<BOT_TOKEN>/getMe"

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "EzyOA Support",
    "username": "ezyoa_support_bot"
  }
}

Khai báo dịch vụ Telegram trong EzyOA

OA Services → Thêm

TELEGRAM_SUPPORT
TELEGRAM_SALES

Tạo Webhook Secret Token

ezyoa_telegram_A7k9xP2mQ4vN8sR6

A-Z
a-z
0-9
_
-

X-Telegram-Bot-Api-Secret-Token: <WEBHOOK_SECRET>

Lấy Webhook URL

https://<web-url>/api/v1/oa/<code>/webhook

https://oa.example.com/api/v1/oa/TELEGRAM_BOT/webhook

• Truy cập được từ Internet.
• Sử dụng HTTPS.
• Không chuyển hướng sang URL khác.
• Trỏ đúng mã dịch vụ.
• Thuộc dịch vụ đang ở trạng thái ACTIVATED.

Đăng ký webhook với Telegram

• <BOT_TOKEN>: Bot Token nhận từ BotFather.
• <WEBHOOK_URL>: URL hiển thị trong EzyOA.
• <WEBHOOK_SECRET>: giá trị đã nhập ở trường Khoá bí mật webhook.

curl --request POST \
  "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "<WEBHOOK_URL>",
    "secret_token": "<WEBHOOK_SECRET>",
    "allowed_updates": [
      "message",
      "my_chat_member"
    ]
  }'

{
  "url": "https://oa.example.com/api/v1/oa/TELEGRAM_BOT/webhook",
  "secret_token": "ezyoa_telegram_A7k9xP2mQ4vN8sR6",
  "allowed_updates": [
    "message",
    "my_chat_member"
  ]
}

• message: nhận tin nhắn người dùng gửi cho bot.
• my_chat_member: nhận sự kiện bot được thêm, gỡ, chặn hoặc bỏ chặn trong chat.

{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}

Kiểm tra trạng thái webhook

curl "https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo"

{
  "ok": true,
  "result": {
    "url": "https://oa.example.com/api/v1/oa/TELEGRAM_BOT/webhook",
    "pending_update_count": 0,
    "allowed_updates": [
      "message",
      "my_chat_member"
    ]
  }
}

Kiểm tra nhận và gửi tin nhắn

Kiểm tra nhận tin

1. Mở bot trên Telegram.
2. Bấm Start hoặc gửi lệnh:

/start

3. Gửi một tin nhắn văn bản.
4. Mở danh sách OA Users hoặc màn hình tin nhắn trong EzyOA.
5. Kiểm tra người dùng và nội dung tin nhắn đã xuất hiện.

Kiểm tra trả lời

1. Mở người dùng Telegram vừa gửi tin.
2. Nhập nội dung trả lời.
3. Bấm gửi.
4. Kiểm tra tin nhắn xuất hiện trong Telegram.

Kiểm tra trạng thái theo dõi

• Khi người dùng bắt đầu hoặc bỏ chặn bot, Telegram có thể gửi update my_chat_member.
• Khi người dùng chặn bot, Telegram gửi trạng thái tương ứng để EzyOA cập nhật người dùng sang trạng thái không còn theo dõi.

Các loại nội dung được hỗ trợ

• Nếu tệp có URL HTTPS công khai, EzyOA gửi URL cho Telegram tải về.
• Nếu URL không công khai, chẳng hạn hệ thống chạy bằng localhost hoặc HTTP, EzyOA tải trực tiếp tệp lên Telegram.
• Các tệp không thuộc loại được nhận diện sẽ được xử lý như tài liệu.

• Caption của media không được xử lý như tin nhắn văn bản.
• EzyOA không đồng bộ toàn bộ danh sách người dùng Telegram theo yêu cầu.
• Không hỗ trợ Telegram notification template riêng.
• Các update như callback_query, edited_message, reaction, poll hoặc location chưa nằm trong luồng xử lý mặc định.

Tích hợp bot vào nhóm

1. Mở BotFather.
2. Chọn bot.
3. Kiểm tra cấu hình cho phép thêm bot vào group.
4. Thêm bot vào group cần sử dụng.
5. Cấp quyền phù hợp nếu bot cần đọc hoặc gửi tin nhắn.
6. Kiểm tra Privacy Mode.

• Command gửi cho bot.
• Tin nhắn trả lời trực tiếp bot.
• Tin nhắn có nhắc tới bot.
• Một số service message liên quan.

Cập nhật cấu hình webhook

curl --request POST \
  "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "<NEW_WEBHOOK_URL>",
    "secret_token": "<NEW_WEBHOOK_SECRET>",
    "allowed_updates": ["message", "my_chat_member"]
  }'

Xoá webhook

curl --request POST \
  "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook"

curl --request POST \
  "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook" \
  --header "Content-Type: application/json" \
  --data '{
    "drop_pending_updates": true
  }'

Xử lý lỗi thường gặp

Bảo mật

• Không commit Bot Token hoặc Webhook Secret Token vào Git.
• Không đặt token trực tiếp trong mã nguồn frontend.
• Không ghi đầy đủ Bot Token vào log.
• Sử dụng Webhook Secret Token ở mọi môi trường production.
• Chỉ mở endpoint webhook qua HTTPS.
• Giới hạn quyền truy cập trang quản trị EzyOA.
• Khi nghi ngờ Bot Token bị lộ, tạo lại token trong BotFather và cập nhật ngay trường Khoá bí mật.
• Sau khi đổi Webhook Secret Token, gọi lại setWebhook.
• Tách bot development và production để tránh tin nhắn thử nghiệm đi vào dữ liệu thật.