Thông báo Telegram, Zalo, Lark

Ngoài 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; cách gọi, xác thực, mã lỗi ở Bắt đầu với TinoPay.

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)

Kiểm token bot: {type, bot_token} → {valid, bot_name, error}. Hiện tên bot; valid là false thì hiện error.
Tìm nơi nhận: {type, bot_token} → {chats: [{id, title, type}], error}; người dùng chọn một nơi nhận, id thành endpoint.
Gửi tin thử: {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.
Tạo ứng dụng: 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: 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 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.