Thông báo biến động số dư qua Telegram: cấu hình bot MONA Pay

Cập nhật 04/09/2026Bản Markdown llms.txt openapi.json

Video hướng dẫn

Thông báo biến động số dư qua Telegram: cấu hình bot MONA Pay từng bước · Xem trên YouTube

Xem transcript video (8 phần)

Tiền vào báo cả nhóm

Bạn muốn kế toán, chủ shop và người giao hàng cùng biết tiền vào mà không có ai phải canh app ngân hàng. Trong vài phút, mình sẽ nối một nhóm Telegram với MONA Pay, từ lúc thêm bot, lấy group_id, chọn tài khoản, sửa mẫu tin đến gửi thử và xử lý lỗi. Cách dashboard không cần viết code. Mỗi giao dịch của tài khoản ACB hoặc VA đã chọn sẽ tạo một tin trong nhóm để mọi người nhìn cùng lúc.

Thêm bot và lấy ID

Tạo nhóm Telegram mới hoặc dùng nhóm công ty đang có, rồi thêm bot MONA Pay với quyền gửi tin nhắn. Tên bot hiển thị trong mục Telegram trên dashboard. Tiếp theo mở nhóm tại web.telegram.org để lấy group_id, tức mã nhóm trong đường dẫn. Nhóm thường có mã bắt đầu bằng dấu trừ. Nếu nhóm bật Chủ đề, lấy thêm topic_id, tức mã chủ đề, để tin đi đúng luồng thay vì rơi vào General.

Tạo cấu hình nhóm

Mở my.monapay.vn, vào mục Telegram và tạo cấu hình. Đặt friendly_name, nghĩa là tên gợi nhớ, dán group_id, thêm topic_id nếu có, rồi chọn nhận mọi tài khoản hay chỉ một virtual_account_id. Giữ mẫu tin mặc định trước để giảm lỗi. Một tài khoản có thể tạo nhiều cấu hình, chẳng hạn nhóm kế toán nhận mọi giao dịch còn nhóm bán hàng chỉ nhận VA của cửa hàng đó.

Chỉnh mẫu tin

Mẫu mặc định dùng các biến đặt trong hai cặp ngoặc nhọn. bank_name là ngân hàng, account_number là tài khoản nhận, amount là số tiền, transaction_date là thời điểm và transaction_content là nội dung chuyển khoản. vao_hay_ra hiển thị VÀO hoặc RA, còn cong_hay_tru hiển thị dấu cộng hoặc trừ. Biến accumulated là số dư sau giao dịch nếu ngân hàng gửi kèm. Telegram hiểu một số thẻ như <b> để in đậm.

Gửi thử hai kiểu

Bấm Gửi thử sau khi lưu cấu hình. Có hai kiểu: is_dummy bằng false gửi tin xác nhận Kết nối thành công; bằng true gửi một giao dịch giả theo message_template, tức mẫu tin bạn đã đặt. Thấy tin trong nhóm là hoàn tất. Nếu muốn cấu hình bằng API, endpoint tạo là POST /api/v1/telegram-configs; mọi request cần Bearer, còn lệnh POST, PUT và DELETE thêm X-Client-Secret.

Gửi lại một giao dịch

Khi một tin giao dịch cũ không tới vì nhóm đổi ID hoặc bot bị đưa ra khỏi nhóm rồi thêm lại, mở mục Giao dịch trên dashboard để gửi lại. Qua API, gọi đường dẫn retry của transaction_id với target_type bằng TELEGRAM. Đây là thao tác cho đúng một giao dịch, không tạo giao dịch mới. Sau khi gửi lại, kiểm tra nhóm và xác nhận cấu hình đang bật trước khi kết luận kênh đã hoạt động bình thường.

Sửa lỗi Telegram

Ba lỗi thường gặp. Không có tin sau Gửi thử thường do bot chưa ở trong nhóm hoặc group_id sai, nhất là thiếu dấu trừ hay phần đầu của mã. Tin rơi vào General nghĩa là thiếu topic_id. Có webhook nhưng không có Telegram thì xem cấu hình có gắn nhầm VA hoặc is_active đang tắt không. Nếu thẻ hiện nguyên dạng, chỉ dùng các thẻ Telegram hỗ trợ như <b>, <i> và <code>.

Hoàn tất cấu hình

Quy trình hoàn chỉnh là thêm bot, lấy đúng mã nhóm, tạo cấu hình, chọn VA, giữ hoặc sửa mẫu rồi gửi thử. Khi nhóm nhận tin mẫu, mọi người có thể theo dõi giao dịch mà không chia sẻ quyền vào app ngân hàng. Một tài khoản tạo được nhiều cấu hình cho nhiều nhóm. Xem đầy đủ biến, endpoint và cách xử lý lỗi tại monapay.vn/docs/telegram. Đăng ký tại my.monapay.vn. Nếu cần hỗ trợ, gọi một chín không không, sáu ba sáu, sáu bốn tám.

Kênh Telegram của MONA Pay gửi 1 tin nhắn vào nhóm Telegram của bạn mỗi khi tài khoản ACB (hoặc VA đã chọn) có tiền vào, không cần viết dòng code nào. Thiết lập trong dashboard mục Telegram gồm 3 việc: thêm bot MONA Pay vào nhóm, dán group_id của nhóm (thêm topic_id nếu nhóm chia chủ đề), bấm “Gửi thử” để thấy tin đầu tiên. Mẫu tin sửa được bằng các biến như {{amount}}, {{transaction_content}}. Kế toán, chủ shop, nhân viên giao hàng đều thấy tiền về cùng lúc, thay cho việc một người ôm điện thoại canh app ngân hàng rồi nhắn lại cho cả nhóm.

Thiết lập trong dashboard (không cần code)

Tạo nhóm Telegram (hoặc dùng nhóm sẵn có của công ty). Thêm bot MONA Pay vào nhóm với quyền gửi tin nhắn; tên bot hiển thị ngay trong dashboard, mục Telegram.
Lấy group_id: mở nhóm trên web.telegram.org, ID nhóm là dãy số trong địa chỉ (nhóm thường bắt đầu bằng dấu trừ, ví dụ -1001234567890); hoặc dùng một bot lấy ID bất kỳ. Nhóm bật “Chủ đề” thì lấy thêm topic_id (số ở cuối đường dẫn của chủ đề) để tin rơi đúng chủ đề.
Tạo cấu hình trong dashboard: đặt tên, dán group_id (+ topic_id), chọn nhận cho mọi tài khoản hay chỉ 1 VA, giữ mẫu tin mặc định hoặc sửa.
Gửi thử: nút “Gửi thử” có 2 kiểu, tin xác nhận kết nối và tin giao dịch giả lập theo đúng mẫu đã đặt. Thấy tin trong nhóm là xong.

Một tài khoản tạo được nhiều cấu hình: nhóm kế toán nhận mọi giao dịch, nhóm bán hàng chỉ nhận VA của cửa hàng đó.

Dashboard MONA Pay cấu hình Telegram Bot và nút bắt đầu thiết lập ngay — Mục Telegram Bot là nơi bắt đầu nối nhóm và gửi thử thông báo, ảnh chụp từ dashboard my.monapay.vn.

Mẫu tin nhắn

Mẫu mặc định (Telegram hiểu thẻ <b> in đậm):

Code

💰 <b>Biến động số dư</b>

Tên ngân hàng: {{bank_name}}
STK: {{account_number}}
Loại giao dịch: tiền {{vao_hay_ra}}
Số tiền: {{cong_hay_tru}}{{amount}}đ
Thời gian: {{transaction_date}}
Nội dung: {{transaction_content}}

Biến	Giá trị khi gửi
`{{bank_name}}`	`ACB`
`{{account_number}}`	Số VA khớp giao dịch, hoặc số tài khoản nhận
`{{vao_hay_ra}}`	`VÀO` với tiền vào, `RA` với tiền ra
`{{cong_hay_tru}}`	`+` hoặc `-`
`{{amount}}`	Số tiền định dạng có dấu chấm, ví dụ `2.500.000`
`{{transaction_date}}`	Thời điểm giao dịch
`{{transaction_content}}`	Nội dung chuyển khoản
`{{accumulated}}`	Số dư sau giao dịch nếu ngân hàng gửi kèm

Mẫu gọn cho nhóm bán hàng:

Code

✅ +{{amount}}đ vào {{account_number}}
{{transaction_content}} · {{transaction_date}}

API /api/v1/telegram-configs

Mọi request cần Authorization: Bearer; POST/PUT/DELETE thêm X-Client-Secret (xem Xác thực).

Endpoint	Việc
`GET /api/v1/telegram-configs`	Danh sách cấu hình
`POST /api/v1/telegram-configs`	Tạo cấu hình
`PUT /api/v1/telegram-configs/{config_id}`	Sửa (gửi trường cần đổi, có `is_active` để tắt tạm)
`DELETE /api/v1/telegram-configs/{config_id}`	Xoá
`POST /api/v1/telegram-configs/test`	Gửi thử vào nhóm

Trường khi tạo:

Trường	Kiểu	Bắt buộc	Ghi chú
`group_id`	string	có	ID nhóm Telegram
`friendly_name`	string	có	Tên gợi nhớ
`message_template`	string	có	Mẫu tin, dùng biến ở bảng trên
`virtual_account_id`	uuid	không	Chỉ nhận giao dịch của VA này; bỏ trống = mọi tài khoản
`topic_id`	string	không	Chủ đề trong nhóm

cURL: tạo cấu hình

Terminal

curl -X POST https://api.monapay.vn/api/v1/telegram-configs \
  -H "Authorization: Bearer $MONA_TOKEN" -H "X-Client-Secret: $MONA_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"-1001234567890","friendly_name":"Nhom ke toan","message_template":"✅ +{{amount}}đ vào {{account_number}}\n{{transaction_content}} · {{transaction_date}}"}'

cURL: gửi thử giao dịch giả lập

Terminal

curl -X POST https://api.monapay.vn/api/v1/telegram-configs/test \
  -H "Authorization: Bearer $MONA_TOKEN" -H "X-Client-Secret: $MONA_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"group_id":"-1001234567890","is_dummy":true}'

is_dummy: false gửi tin “Kết nối thành công” để kiểm tra bot đã vào nhóm; true gửi tin giao dịch giả theo message_template (bỏ trống thì dùng mẫu mặc định).

PHP

PHP

<?php
$body = [
    'group_id' => '-1001234567890',
    'friendly_name' => 'Nhom ke toan',
    'message_template' => "✅ +{{amount}}đ vào {{account_number}}\n{{transaction_content}} · {{transaction_date}}",
];
$ch = curl_init('https://api.monapay.vn/api/v1/telegram-configs');
curl_setopt_array($ch, [
    CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer ' . getenv('MONA_TOKEN'), 'X-Client-Secret: ' . getenv('MONA_SECRET')],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
if (empty($res['success'])) throw new RuntimeException($res['message'] ?? 'Tạo cấu hình Telegram thất bại');

Node

JavaScript

const r = await fetch('https://api.monapay.vn/api/v1/telegram-configs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.MONA_TOKEN}`, 'X-Client-Secret': process.env.MONA_SECRET },
  body: JSON.stringify({
    group_id: '-1001234567890',
    friendly_name: 'Nhom ke toan',
    message_template: '✅ +{{amount}}đ vào {{account_number}}\n{{transaction_content}} · {{transaction_date}}',
  }),
});
const { success, message } = await r.json();
if (!success) throw new Error(message);

Gửi lại một giao dịch

Tin không tới (nhóm đổi ID, bot bị kick rồi thêm lại) thì gửi lại từ dashboard mục Giao dịch, hoặc gọi POST /api/v1/acb/virtual-account/transactions/{transaction_id}/retry với {"target_type":"TELEGRAM"} (xem Giao dịch).

Lỗi thường gặp

Tình huống	Nguyên nhân	Cách xử lý
Gửi thử báo lỗi, không có tin	Bot chưa được thêm vào nhóm, hoặc `group_id` sai (thiếu dấu trừ, thiếu `100` đầu)	Thêm bot vào nhóm, copy lại ID từ web.telegram.org
Tin rơi vào chủ đề “General” thay vì chủ đề mong muốn	Thiếu `topic_id`	Thêm `topic_id` vào cấu hình
Có webhook nhưng không có tin Telegram	Cấu hình gắn VA khác, hoặc `is_active` đang tắt	Kiểm tra lại VA và trạng thái cấu hình
Tin hiện thẻ `<b>` thô	Mẫu dùng thẻ Telegram không hỗ trợ	Chỉ dùng `<b>`, `<i>`, `<code>`