# Thông báo Telegram, Zalo, Lark

Ngoài [webhook](/docs/tinopay-webhook), TinoPay gửi thông báo từng giao dịch vào Telegram, Zalo hoặc Lark. Mỗi ứng dụng thông báo gắn một tài khoản ngân hàng và lọc theo tài khoản ảo như webhook. Các route ở nhóm Thông báo của [API Reference](/docs/reference#tinopay); cách gọi, xác thực, mã lỗi ở [Bắt đầu với TinoPay](/docs/tinopay-start).

Cập nhật: 2026-10-25. Nguồn: module TinoPay của Tino và tài liệu TinoPay API v1.

## Loại ứng dụng

| `type` | Bot | `endpoint` (nơi nhận) |
| --- | --- | --- |
| `telegram` | mặc định bot chung **@allpay_telebot**; gửi `bot_token` để dùng bot riêng | bot chung: ID nhóm bắt đầu bằng `-` (thêm @allpay_telebot vào nhóm); bot riêng: ID nhóm (`-…`) hoặc chat cá nhân (số dương) |
| `zalo` | bắt buộc bot riêng (`bot_token` từ Zalo Bot Creator) | `chat_id` Zalo của chat cá nhân hoặc nhóm (nhóm bắt đầu bằng `zgr-`) |
| `lark` | URL webhook bot Lark, không có `bot_token` | `https://open.larksuite.com/open-apis/bot/v2/hook/…` (hoặc `open.feishu.cn`) |

`bot_token` không bao giờ được trả về: danh sách chỉ có `bot_token_masked`. Khi làm giao diện, để ô token là ô mật khẩu và không điền lại khi sửa.

## Thêm ứng dụng (bot riêng)

1. [Kiểm token bot](/docs/api/tinopay-post-notification-apps-bot-info): `{type, bot_token}` → `{valid, bot_name, error}`. Hiện tên bot; `valid` là `false` thì hiện `error`.
2. [Tìm nơi nhận](/docs/api/tinopay-post-notification-apps-find-chats): `{type, bot_token}` → `{chats: [{id, title, type}], error}`; người dùng chọn một nơi nhận, `id` thành `endpoint`.
3. [Gửi tin thử](/docs/api/tinopay-post-notification-apps-test): `{type, endpoint, bot_token}` gửi một tin nhắn thật → `{connected, chat_title}`. Chỉ cho lưu khi `connected` là `true`; Telegram có `chat_title` để điền sẵn tên.
4. [Tạo ứng dụng](/docs/api/tinopay-post-notification-apps): `type`, `name` (tối đa 250 ký tự), `endpoint`, `bot_token`, `bank_account_id`, `virtual_accounts` (rỗng là mọi tài khoản ảo), `status` (`active` mặc định, `inactive`) → 201. `type` không đổi được sau khi tạo.

Bước 2 theo từng loại:

- Telegram trả ngay nhóm, người đã nhắn bot trong 24 giờ. `error` khác `null` (bot đang gắn webhook của hệ thống khác): cho nhập ID tay.
- Zalo không lưu tin cũ: request chờ tới khoảng 20 giây và chỉ bắt tin nhắn gửi bot trong lúc chờ (nhóm: nhắc tên bot). Báo người dùng "hãy nhắn bot ngay", đặt timeout HTTP ít nhất 30 giây. Hết giờ chưa có tin thì `chats` rỗng: cho thử lại hoặc nhập tay.

Bot chung Telegram: bỏ bước 1, 2; nhập ID nhóm, bước 3 không gửi `bot_token`. Lark: chỉ bước 3, 4 với `endpoint` là URL webhook.

Bước 2 và 3 không tự thử lại khi lỗi mạng (thử lại sẽ chờ lâu gấp nhiều lần hoặc gửi tin thử hai lần): để người dùng bấm lại.

## Sửa ứng dụng

- Bước 1–3 khi sửa gửi `app_id` thay `bot_token` để dùng token đang lưu; `app_id` phải là ứng dụng của merchant này, không thì 404 `RESOURCE_NOT_FOUND`.
- [Sửa ứng dụng](/docs/api/tinopay-patch-notification-apps-app): chỉ gửi trường cần đổi, không gửi `type`.

| `bot_token` khi sửa | Kết quả |
| --- | --- |
| không gửi | giữ token cũ |
| chuỗi mới | đổi sang token mới |
| `null` | Telegram về bot chung (`endpoint` phải là ID nhóm `-…`); Zalo không bỏ được token |

Đổi sang `bank_account_id` không thuộc merchant: 404 `BANK_ACCOUNT_NOT_FOUND`.

## Theo dõi lỗi gửi

[Danh sách ứng dụng](/docs/api/tinopay-get-notification-apps) có `last_error`, `last_error_at`: lỗi của lần gửi gần nhất (token bị thu hồi, bot bị đưa khỏi nhóm…). Hiện cảnh báo "Lỗi kết nối" kèm `last_error`; lần gửi sau thành công thì tự về `null`. Merchant tạm ngưng thì ngừng gửi thông báo, giống webhook.