# Kết nối Telegram

Kết nối bot Telegram, và nếu muốn cả tài khoản Telegram Business, để tin nhắn của khách trên Telegram về Hộp thư.

Kết nối **bot Telegram** để khách nhắn cho bot về **Hộp thư**, cạnh các kênh khác. Có **Telegram Premium**, bạn còn liên kết được bot với tài khoản của chính mình qua **Telegram Business**: tin khách gửi vào tài khoản Telegram cá nhân của bạn cũng về Hộp thư, và cả đội trả lời thay bạn.

Hạ Tầng dùng Bot API chính thức của Telegram: không giữ phiên đăng nhập tài khoản của bạn, không cần duyệt ứng dụng.

## Kênh này hỗ trợ gì

| Chiều | Hỗ trợ |
|---|---|
| Nhận | Văn bản và chú thích, ảnh, video, tin thoại và âm thanh, tài liệu, ảnh động, sticker (sticker emoji hiện dạng chữ), vị trí, danh bạ, trả lời trích dẫn |
| Gửi | Văn bản, ảnh, video, tin thoại, âm thanh và tài liệu tới 20 MB (lớn hơn gửi dạng link tải), trích tin của khách; thu hồi tin đã gửi |
| Sửa và xoá | Tin khách sửa được cập nhật; tin bị xoá trong chat Telegram Business có ghi chú nội bộ |
| Từ ứng dụng Telegram | Với Telegram Business, tin bạn trả lời từ ứng dụng Telegram cũng hiện trong hội thoại |
| Đã xem | Chỉ với chat Telegram Business: khách thấy tin đã được xem khi nhân viên mở hội thoại |

Chỉ **chat riêng** về Hộp thư. Tin trong nhóm và kênh bị bỏ qua.

## Trước khi bắt đầu

- Một tài khoản Telegram để tạo bot.
- Với Telegram Business: tài khoản khách nhắn tới phải có **Telegram Premium**.
- Một website ở **Hỗ trợ khách hàng → Kênh**, và mức **Quản lý** ở module Hỗ trợ khách hàng.

## Bước 1: Tạo bot

1. Trong Telegram, mở **@BotFather** và gửi `/newbot`.
2. Đặt tên cho bot và tên người dùng kết thúc bằng `bot`, ví dụ `mochuong_tea_bot`.
3. BotFather trả về một **token** dạng `123456789:AA…`. Giữ bí mật như mật khẩu.

## Bước 2: Kết nối bot

1. Vào **Hỗ trợ khách hàng → Kênh**, bấm **Thêm kênh** và chọn **Telegram** trong nhóm **Ứng dụng nhắn tin**.
2. Nếu doanh nghiệp có nhiều website, chọn một website ở **Gắn kết nối mới vào site**.
3. Dán token vào ô **Token của bot (từ @BotFather)** và bấm **Kết nối bot**.

![Trang kết nối Telegram với ô token của bot](https://hatang.dev/help/img/vi/channels/connect-telegram.webp)

Hạ Tầng kiểm tra token, kết nối bot và hiện bot với trạng thái **Hoạt động**. Trang của bot hiện link `t.me/<tên_bot>`. Đặt link này lên website, trang mạng xã hội hoặc in thành mã QR để khách nhắn cho bot.

> [!WARNING]
> Mỗi bot Telegram chỉ chuyển tin về được một công cụ. Nếu bạn kết nối cùng bot với công cụ khác, công cụ đó sẽ nhận thay và tin không về Hạ Tầng nữa. Hãy dùng bot riêng cho mỗi công cụ.

## Bước 3 (tuỳ chọn): Liên kết Telegram Business

Khách thường nhắn thẳng vào tài khoản của chủ shop hơn là nhắn cho bot. Nếu có Telegram Premium:

1. Trong ứng dụng Telegram, mở **Cài đặt → Telegram Business → Chatbot**.
2. Nhập tên người dùng của bot đã kết nối, chọn những chat bot được truy cập và **cho phép bot trả lời**.
3. Trên trang của bot ở **Hỗ trợ khách hàng → Kênh**, thẻ **Telegram Business** hiện **Telegram Business: *tên bạn* · được trả lời**.

![Trang của bot Telegram đã liên kết Telegram Business](https://hatang.dev/help/img/vi/channels/telegram-page.webp)

Thẻ hiện **chỉ đọc (bật quyền trả lời trong Telegram)** khi bot được đọc nhưng chưa được trả lời, và **đã tắt** khi liên kết đang tạm dừng. Từ đó, tin khách gửi vào tài khoản của bạn về Hộp thư. Khi nhân viên trả lời, khách thấy tin gửi từ tài khoản của bạn.

## Giới hạn

| Mục | Giới hạn |
|---|---|
| Trả lời trong chat Telegram Business | Trong **24 giờ** kể từ tin cuối của khách. Quá hạn, Hộp thư không gửi và thêm ghi chú nội bộ; hãy trả lời từ ứng dụng Telegram hoặc chờ khách nhắn lại |
| Trả lời trong chat với bot | Không giới hạn thời gian |
| Tệp nhận | Đến 20 MB |
| Chú thích | Một tệp kèm đoạn chữ đến 1.024 ký tự được gửi thành một tin có chú thích |
| Thu hồi tin | Trong chat với bot, Telegram cho bot xoá tin của mình trong 48 giờ |

Khi khách chia sẻ danh bạ của chính họ, số điện thoại được lưu vào hồ sơ khách. Muốn giao hội thoại Telegram cho một nhóm, tích **Telegram** ở mục **Kênh (không chọn = mọi kênh)** của [quy tắc phân phối](https://hatang.dev/vi/help/automation/routing-rules).

## Đổi token và ngắt kết nối

Nếu bạn thu hồi token trong @BotFather (`/revoke`), bot ngừng nhận tin, và lần trả lời thất bại tiếp theo sẽ chuyển trạng thái sang **Cần kết nối lại**. Mở trang của bot, bấm **Kết nối lại** và dán token mới. Kết nối lại cùng bot thì hội thoại được giữ nguyên.

**Ngắt kết nối** dừng tin mới về Hộp thư. Hội thoại cũ vẫn được giữ.

## Xử lý sự cố

| Hộp thư báo | Nguyên nhân | Cách xử lý |
|---|---|---|
| khách đã chặn bot Telegram (hoặc xoá tài khoản) | Khách chặn bot | Liên hệ khách qua kênh khác; khách bỏ chặn và nhắn lại thì gửi được |
| token của bot Telegram không còn hợp lệ | Token đã đổi trong @BotFather | Lấy token mới từ @BotFather rồi kết nối lại bot |
| bot Telegram đang gửi quá nhanh | Giới hạn tốc độ của Telegram | Đợi vài giây rồi gửi lại |
| ngoài khung giờ trả lời của kênh | Chat Telegram Business đã quá 24 giờ | Trả lời từ ứng dụng Telegram, hoặc chờ khách |

Sự cố khác:

- **Kết nối báo "Telegram rejected this token".** Token bị gõ sai hoặc đã bị thu hồi. Chép lại từ @BotFather.
- **Không có tin nào về.** Bot đang kết nối với công cụ khác, hoặc đó là chat nhóm. Ngắt kết nối ở công cụ kia rồi kết nối lại ở đây; chỉ chat riêng được hỗ trợ.