Pine Script alert webhook: mẫu JSON cho bot

Sai sót phổ biến nhất khi làm TradingView Webhook Bot không nằm ở phía server, mà nằm ở phía Pine Script. Nội dung tin nhắn sai định dạng hoặc thiếu trường khiến server phải đoán, và bot đoán sai thì đặt sai lệnh. Bài viết này tập trung vào phần dễ sai nhất: cấu trúc payload.

Vì sao phải quan tâm tới nội dung alert

Trong một hệ thống webhook, phần Pine Script và phần server là hai đội làm việc với nhau qua một hợp đồng duy nhất: nội dung tin nhắn. Nếu hợp đồng mơ hồ, hai bên sẽ hiểu khác nhau.

Ví dụ, Pine Script gửi chuỗi "BUY BTCUSDT". Server phải tự đoán khối lượng, tự đoán giá, tự đoán khung thời gian. Mỗi chỗ đoán là một chỗ có thể sai. Ngược lại, nếu Pine Script gửi một JSON có đủ mã cặp, hướng lệnh, giá tham chiếu, khung thời gian và mã tín hiệu, server chỉ cần đọc và làm theo.

Vì vậy nguyên tắc thiết kế payload rất đơn giản: Pine Script nên gửi mọi thứ nó biết mà server khó hoặc không thể suy ra được, và server tự suy ra phần còn lại. Pine Script biết chính xác nến nào đã kích hoạt tín hiệu, giá nào được dùng để tính, và hướng lệnh nào được chọn. Server thì biết số dư, biết khối lượng tối thiểu của sàn, biết trạng thái vị thế hiện tại.

Ba cách đưa tín hiệu ra khỏi Pine Script

Có ba đường để tín hiệu đi từ script ra thế giới bên ngoài, và chúng không tương đương nhau.

Cách thứ nhất là gọi hàm alert trực tiếp trong script. Đây là cách linh hoạt nhất, vì bạn kiểm soát hoàn toàn nội dung, thời điểm và điều kiện gọi.

Cách thứ hai là tạo alert condition, tức là đăng ký một điều kiện để TradingView hiển thị nó trong danh sách chọn của hộp thoại alert. Cách này đơn giản hơn nhưng nội dung tin nhắn phần lớn là tĩnh.

Cách thứ ba là tạo alert từ một chiến lược đã viết bằng Pine Script, dùng các tham số chèn thông điệp trong hàm vào lệnh. Cách này phù hợp nhất khi bạn muốn bot giao dịch đúng theo chiến lược đã backtest, vì TradingView cung cấp thêm các placeholder về hướng lệnh và khối lượng của chiến lược.

Cách làm	Nội dung động	Cần viết code	Phù hợp nhất với
Gọi alert trong script	Có, tự do	Có	bot giao dịch thật
alertcondition	Hạn chế	Một dòng	cảnh báo đơn giản
Alert từ chiến lược	Qua tham số chèn thông điệp	Có, vì phải sửa hàm vào lệnh	bot chạy theo chiến lược

So sánh alert, alertcondition và alert_message

Ba khái niệm này hay bị dùng lẫn, nên cần tách rõ.

Hàm alert là một lời gọi chủ động. Khi dòng lệnh chạy tới nó, TradingView sẽ phát thông báo nếu điều kiện đi kèm đúng. Bạn có thể truyền vào một chuỗi động được dựng ngay trong script, kèm tần suất gửi như mỗi lần nến đóng, mỗi nến một lần, hay mỗi lần tính toán.

Hàm alertcondition mang tính khai báo. Bạn đăng ký một điều kiện cùng tiêu đề và thông điệp. Điều kiện này xuất hiện trong hộp thoại tạo alert, và bạn tạo alert cho nó như tạo alert cho một chỉ báo. Nội dung thông điệp ở đây chủ yếu là tĩnh, muốn đưa giá trị động thì phải đi đường vòng bằng placeholder dạng plot.

Tham số chèn thông điệp trong các hàm vào lệnh của chiến lược là một chuỗi bạn gắn kèm cho từng quyết định vào lệnh. Khi TradingView phát thông báo cho lệnh đó, nó có thể chèn chuỗi này vào payload nếu bạn dùng đúng placeholder tương ứng. Đây là cơ chế phổ biến nhất để bot biết chiến lược vừa làm gì.

Một hiểu nhầm cần loại bỏ ngay: chuỗi bạn viết trong Pine Script không được TradingView thay placeholder. Placeholder chỉ được thay trong nội dung tin nhắn bạn gõ trong hộp thoại alert. Vì vậy nếu muốn payload chứa giá đóng cửa, bạn phải tự chuyển giá đó thành chuỗi trong Pine Script rồi ghép vào JSON, không thể viết placeholder vào chuỗi Pine Script và mong nó được thay.

Cấu trúc payload JSON tốt cho bot

Đây là phần quan trọng nhất của cả bài. Một payload tốt cần đủ trường để server không phải đoán, nhưng không quá nhiều để bạn phải kiểm tra hàng chục biến.

Nhóm trường bắt buộc gồm: mã cặp, khung thời gian, hướng lệnh và mã tín hiệu. Thiếu bất kỳ trường nào trong nhóm này, server sẽ phải đoán điều gì đó.

Nhóm trường nên có gồm: giá tham chiếu, thời điểm nến, tên chiến lược, và khoá bí mật xác thực.

Nhóm trường tuỳ chọn gồm: khối lượng gợi ý, mức dừng lỗ, mức chốt lời, ghi chú. Với các trường này nên để trống được, và server phải xử lý đúng khi chúng vắng mặt.

Bảng gợi ý cấu trúc:

Trường	Kiểu dữ liệu	Bắt buộc	Ghi chú
secret	chuỗi	Có	xác thực tin nhắn
symbol	chuỗi	Có	mã cặp đúng chuẩn sàn
interval	chuỗi	Có	ví dụ 5, 15, 60, D
action	chuỗi	Có	buy, sell, close, close_all
price	số	Nên có	giá dùng để tính toán
qty	số	Tuỳ	để trống thì server tự tính
sl	số	Tuỳ	dừng lỗ, có thể rỗng
tp	số	Tuỳ	chốt lời, có thể rỗng
id	chuỗi	Có	mã tín hiệu chống trùng
strategy	chuỗi	Nên có	phân biệt nhiều chiến lược
time	chuỗi	Nên có	thời gian nến

Mẫu JSON 1: bot đặt lệnh crypto

Với bot crypto, bạn cần mã cặp đúng định dạng của sàn và khối lượng cho phép để trống nhằm để server tính theo số dư.

{"secret":"KEY_ABC","symbol":"BTCUSDT","interval":"15","action":"buy","price":{{close}},"qty":0,"sl":0,"tp":0,"id":"ema15-BTC-{{time}}","strategy":"ema-cross-v3","time":"{{time}}"}

Với mẫu trên, server có thể đọc trường khối lượng bằng không nghĩa là "tự tính theo cấu hình", hoặc thay bằng giá trị thật nếu bạn muốn Pine Script quyết định khối lượng.

Mẫu JSON 2: bot MT5

Với MetaTrader 5, tên cặp có thể có hậu tố tuỳ broker, ví dụ XAUUSD.a hoặc EURUSDm. Vì vậy nên để phần hậu tố cho server ghép vào, tránh gõ cứng trong Pine Script.

{"secret":"KEY_MT5","symbol":"XAUUSD","interval":"60","action":"buy","price":{{close}},"lots":0,"sl_pips":200,"tp_pips":400,"id":"gold-h1-{{time}}","strategy":"breakout-gold","time":"{{time}}"}

Ở đây dừng lỗ và chốt lời nên truyền theo số pip hoặc số điểm, vì Pine Script biết được biên độ nhưng server mới biết quy đổi ra giá của từng broker.

Mẫu JSON 3: bot chứng khoán Việt Nam

Với chứng khoán, đơn vị khối lượng là cổ phiếu và bước khối lượng là một lô chẵn, nên payload nên tách rõ khối lượng mong muốn và để server làm tròn.

{"secret":"KEY_VN","symbol":"FPT","interval":"D","action":"buy","price":{{close}},"qty":100,"id":"fpt-D-{{time}}","strategy":"momentum-vn","time":"{{time}}"}

Một điểm cần lưu ý là khung thời gian ngày không có khái niệm nến đang chạy theo cùng cách như khung phút, nên hãy dùng chế độ gửi khi đóng nến để tránh tín hiệu bắn khi phiên chưa kết thúc.

Cách truyền khối lượng và giá từ chiến lược

Nếu bạn tạo alert từ chiến lược, cách làm chuẩn là gắn chuỗi thông điệp cho từng lệnh, rồi dùng placeholder để TradingView chèn chuỗi đó vào payload.

Về mặt cấu trúc, bạn làm ba việc. Một là dựng một hàm nhỏ nhận các tham số cần thiết và trả về chuỗi JSON đã ghép xong. Hai là truyền chuỗi đó vào tham số chèn thông điệp khi gọi hàm vào lệnh. Ba là trong hộp thoại alert, dùng đúng placeholder để lấy chuỗi thông điệp ra, đồng thời chèn thêm các trường bạn muốn như khối lượng hoặc giá.

Ví dụ chiến lược tối giản có thông điệp động:

//@version=5
strategy("EMA Cross Webhook", overlay=true)

fastLen = input.int(9, "EMA nhanh")
slowLen = input.int(21, "EMA cham")
secret  = input.string("KEY_ABC", "Secret")

emaFast = ta.ema(close, fastLen)
emaSlow = ta.ema(close, slowLen)

mkJson(action) =>
    '{"secret":"' + secret + '","symbol":"' + syminfo.ticker + '","interval":"' + timeframe.period + '","action":"' + action + '","price":' + str.tostring(close, "#.########") + ',"id":"' + syminfo.ticker + '-' + timeframe.period + '-' + str.tostring(time) + '","strategy":"ema-cross"}'

longCond  = ta.crossover(emaFast, emaSlow)
shortCond = ta.crossunder(emaFast, emaSlow)

if longCond
    strategy.entry("L", strategy.long, alert_message = mkJson("buy"))

if shortCond
    strategy.entry("S", strategy.short, alert_message = mkJson("sell"))

Trong hộp thoại alert tạo từ chiến lược này, nội dung tin nhắn sẽ là placeholder lấy chuỗi thông điệp:

{{strategy.order.alert_message}}

Cách làm này có một điểm mạnh: bạn có thể ghép thêm bất kỳ trường nào mà Pine Script tính được, kể cả giá trị của chỉ báo. Nhờ đó server không cần cài lại chỉ báo để tính lại, tránh sai lệch giữa hai bên.

Bốn bẫy khi dựng JSON trong Pine Script

Bẫy thứ nhất là giá trị rỗng. Trong Pine Script, một chỉ báo mới bắt đầu tính sẽ trả về giá trị rỗng trong vài nến đầu. Nếu bạn ghép thẳng giá trị đó vào chuỗi, chuỗi JSON sẽ chứa chữ na hoặc một giá trị không phải số, và server sẽ từ chối payload. Cách tránh là kiểm tra giá trị bằng hàm kiểm tra rỗng trước khi gọi alert, và không gọi alert khi dữ liệu chưa đủ.

Bẫy thứ hai là số mũ khoa học. Một số giá trị rất nhỏ hoặc rất lớn có thể được chuyển thành chuỗi dạng số mũ, ví dụ 1e-05. Nhiều thư viện JSON vẫn đọc được nhưng một số ngôn ngữ phía server xử lý khác nhau. Cách tránh là chỉ định số chữ số thập phân khi chuyển số thành chuỗi, để giá trị luôn ở dạng bạn kiểm soát được.

Bẫy thứ ba là dấu nháy trong giá trị. Nếu bạn đưa tên chiến lược hoặc ghi chú có dấu nháy kép vào chuỗi, JSON sẽ hỏng cấu trúc. Cách tránh là thay dấu nháy bằng ký tự khác, hoặc chỉ dùng các ký tự an toàn trong mọi trường dạng chuỗi.

Bẫy thứ tư là tần suất gửi. Nếu bạn gọi alert ở thân script mà không giới hạn tần suất, TradingView có thể gọi với tần suất bạn không mong muốn. Cách tránh là chọn tần suất gửi khi nến đóng cho mọi tín hiệu đặt lệnh, và chỉ dùng các tần suất khác cho mục đích cảnh báo.

Tạo mã tín hiệu để chống trùng

Mã tín hiệu là trường người mới hay bỏ qua nhất, nhưng nó lại là thứ cứu bạn khỏi việc mở nhiều lệnh cho cùng một tín hiệu.

Ý tưởng rất đơn giản: với mỗi quyết định vào lệnh, sinh ra một chuỗi định danh duy nhất dựa trên những thứ không đổi trong cùng tín hiệu đó. Một tổ hợp thực tế gồm mã cặp, khung thời gian, hướng lệnh và thời điểm nến.

Khi server nhận payload, nó lấy mã tín hiệu này và lưu lại. Nếu một payload khác có cùng mã tín hiệu xuất hiện trong khoảng thời gian bạn cấu hình, server bỏ qua. Cơ chế này xử lý được ba tình huống thường gặp: alert bắn hai lần do cấu hình sai tần suất, người dùng bấm thêm một alert nữa cho cùng chiến lược, và mạng chập khiến TradingView gửi lại.

Một điểm cần chú ý là mã tín hiệu phải ổn định trong một nến. Nếu bạn đưa vào đó một giá trị thay đổi liên tục như giá hiện tại, mã sẽ khác nhau mỗi lần gửi và cơ chế chống trùng mất tác dụng.

Kiểm thử payload trước khi gắn vào bot

Trước khi cho payload chạy vào bot thật, hãy kiểm thử theo ba lớp.

Lớp thứ nhất là kiểm tra nội dung thô. Dùng một dịch vụ nhận webhook tạm thời, tạo alert trỏ tới đó, và xem nội dung chính xác mà TradingView gửi đi. Hãy đọc từng ký tự, đặc biệt là các trường số, để chắc chắn không có dấu nháy kép dư và không có giá trị rỗng.

Lớp thứ hai là kiểm tra phân tích cú pháp. Đưa nội dung thô đó vào server ở chế độ chỉ phân tích, in ra các trường đã đọc được, chưa gọi API sàn. Nếu trường nào ra rỗng hoặc sai kiểu dữ liệu, sửa ở phía Pine Script.

Lớp thứ ba là kiểm tra quyết định. Cho server chạy trên tài khoản demo vài chục lần với cùng payload, rồi so sánh lệnh server đặt với điều bạn kỳ vọng. Lớp này phát hiện các lỗi về khối lượng, làm tròn và giá.

Checklist payload trước khi chạy tiền thật

• JSON hợp lệ và nằm trên một dòng.
• Có đủ bốn trường bắt buộc: mã cặp, khung thời gian, hướng lệnh, mã tín hiệu.
• Trường số không nằm trong dấu nháy kép.
• Không có giá trị rỗng hoặc giá trị kiểu số mũ ngoài ý muốn.
• Có khoá bí mật và server từ chối khi khoá sai.
• Mã tín hiệu ổn định trong cùng một nến.
• Tần suất gửi là khi nến đóng cho mọi tín hiệu vào lệnh.
• Đã kiểm thử qua cả ba lớp: nội dung thô, phân tích cú pháp, quyết định trên demo.
• Đã xác nhận không dùng placeholder bên trong chuỗi Pine Script.
• Đã ghi lại phiên bản payload, để khi sửa Pine Script bạn biết bot đang chạy phiên bản nào.

Cách gỡ lỗi khi alert không bắn

Phần khó nhất của việc làm alert không phải là viết được, mà là biết vì sao nó im lặng. Có một quy trình kiểm tra theo thứ tự giúp bạn tìm ra nguyên nhân nhanh hơn nhiều so với việc sửa thử ngẫu nhiên.

Bước một, kiểm tra điều kiện có thực sự xảy ra hay không. Cách nhanh nhất là dùng hàm hiển thị nhãn vẽ lên chart tại đúng chỗ bạn gọi alert. Nếu nhãn không xuất hiện trên chart, điều kiện của bạn chưa từng đúng, và mọi thứ phía sau đều vô nghĩa. Rất nhiều trường hợp người học tưởng lỗi webhook nhưng thực chất điều kiện chưa bao giờ được thoả.

Bước hai, kiểm tra alert đã được tạo từ đúng script hay chưa. Trên một chart có thể có nhiều script cùng chạy, và hộp thoại alert cho phép bạn chọn nguồn. Nếu bạn chọn nhầm chỉ báo khác, alert sẽ không bao giờ bắn đúng.

Bước ba, kiểm tra tần suất gửi và chế độ kiểm tra trong hộp thoại. Nếu script gọi alert theo kiểu mỗi lần nến đóng nhưng trong hộp thoại bạn lại để chế độ chỉ một lần, alert sẽ bắn lần đầu rồi tắt vĩnh viễn.

Bước bốn, kiểm tra giới hạn của gói tài khoản. Mỗi gói có trần số alert đang hoạt động, và khi đã chạm trần, alert mới có thể không được kích hoạt như bạn mong đợi.

Bước năm, kiểm tra đầu nhận. Đổi tạm địa chỉ webhook sang một dịch vụ nhận tạm thời. Nếu tin nhắn tới đó, vấn đề nằm ở server của bạn; nếu không tới, vấn đề nằm ở phía TradingView.

Bảng chẩn đoán nhanh:

Hiện tượng	Nguyên nhân hay gặp nhất	Cách xác nhận
Không có nhãn trên chart	điều kiện chưa từng đúng	vẽ nhãn tại chỗ gọi alert
Có nhãn nhưng không có tin nhắn	chọn sai nguồn hoặc hết hạn alert	mở danh sách alert kiểm tra
Bắn một lần rồi im	chế độ chỉ một lần	đổi sang gửi khi đóng nến
Bắn nhiều lần trong một nến	tần suất gửi sai	dùng tần suất đóng nến
Tin nhắn tới nhưng JSON lỗi	ghép chuỗi sai, có giá trị rỗng	đọc nội dung thô
Tin nhắn tới chậm	server quá tải hoặc mạng chập	đo thời gian trong log

Giảm số lượng alert bằng cách gộp nhiều cặp

Mỗi gói TradingView có giới hạn số alert đang hoạt động, nên khi bạn muốn theo dõi nhiều cặp cùng lúc, số alert tăng theo cấp số nhân với số khung thời gian.

Có một mẹo thực tế giúp giảm mạnh số alert: viết script dùng mã cặp động thay vì viết riêng cho từng cặp. Thay vì gõ cứng mã cặp trong chuỗi, bạn lấy mã cặp từ thông tin biểu tượng của chart. Khi đó cùng một script dùng được cho mọi cặp, và mỗi cặp chỉ cần một alert.

Tuy nhiên cần tỉnh táo về đánh đổi. Gộp nhiều cặp vào một script nghĩa là logic phải xử lý được mọi cặp, bao gồm cả những cặp có đặc tính giá rất khác nhau. Một ngưỡng phù hợp cho vàng có thể hoàn toàn không phù hợp cho một cặp tiền tệ biến động thấp.

Cách cân bằng hợp lý là chia theo nhóm. Nhóm tài sản có cùng đặc tính biến động dùng chung một script với tham số điều chỉnh được, và mỗi cặp có một alert riêng. Cách này vừa tiết kiệm số alert vừa giữ được khả năng tinh chỉnh.

Một chi tiết kỹ thuật cần nhớ khi dùng mã cặp động là định dạng tên cặp khác nhau giữa các nguồn dữ liệu. TradingView có cách viết riêng, sàn giao ngay có cách viết khác, và hợp đồng tương lai lại có cách viết khác nữa. Hãy để server chuẩn hoá tên cặp, thay vì cố viết chuẩn ở phía script.

Payload cho bot thông báo và bot tự động khác nhau thế nào

Nếu mới bắt đầu, bạn nên viết payload cho bot thông báo trước, rồi mở rộng dần. Sự khác biệt giữa hai loại nằm ở mức độ chắc chắn mà server cần có.

Với bot thông báo, payload chỉ cần đủ nội dung để bạn hiểu. Sai một trường cũng không gây hậu quả tài chính, và bạn có thể đọc rồi tự quyết định. Giai đoạn này payload thường rất ngắn, chỉ gồm mã cặp, hướng và giá.

Với bot tự động, mọi trường đều phải chắc chắn. Không được có trường rỗng, không được để server tự đoán mã cặp, và nhất thiết phải có mã tín hiệu. Một trường sai có thể dẫn tới lệnh sai khối lượng hoặc sai mã, và hậu quả là tiền.

Bảng so sánh mức yêu cầu:

Trường	Bot thông báo	Bot tự động
mã cặp	bắt buộc	bắt buộc, phải đúng định dạng sàn
hướng lệnh	bắt buộc	bắt buộc
giá	nên có	bắt buộc, dùng để tính khối lượng
khung thời gian	tuỳ	bắt buộc, dùng để chống trùng
mã tín hiệu	không cần	bắt buộc
khoá bí mật	nên có	bắt buộc
dừng lỗ, chốt lời	không cần	nên có

Cách chuyển đổi hợp lý là giữ nguyên một script nhưng bật tắt phần gửi bằng tham số đầu vào. Giai đoạn học, bạn chạy ở chế độ thông báo. Khi đã tin vào tín hiệu, bạn chuyển sang chế độ đầy đủ mà không phải viết lại script.

Bảo trì payload khi chiến lược thay đổi

Một sai lầm vận hành rất tốn kém là sửa script nhưng quên cập nhật bên nhận, hoặc ngược lại. Kết quả là bot vẫn chạy nhưng hiểu sai, và bạn chỉ phát hiện khi nhìn lại lịch sử giao dịch.

Cách phòng ngừa gọn nhất là đưa phiên bản vào payload. Thêm một trường phiên bản với giá trị bạn tăng mỗi khi có thay đổi. Bên nhận kiểm tra trường này và từ chối những phiên bản không được hỗ trợ, thay vì cố xử lý và gây lệnh sai.

Nguyên tắc thứ hai là mở rộng thì dễ, thu hẹp thì khó. Khi cần thêm trường, hãy thêm với giá trị mặc định hợp lý để bên nhận cũ vẫn chạy được. Khi cần bỏ trường, hãy giữ nó thêm một thời gian rồi mới xoá.

Nguyên tắc thứ ba là ghi lại mọi thay đổi payload vào một tệp ghi chú, kèm ngày thay đổi và lý do. Sáu tháng sau, khi bạn tự hỏi vì sao bot xử lý khác đi, tệp này là thứ trả lời câu hỏi đó.

Cuối cùng, hãy kiểm thử trên demo sau mỗi lần thay đổi payload, kể cả khi thay đổi đó chỉ là thêm một trường. Sai sót nhỏ ở phần ghép chuỗi có thể làm JSON hỏng và bot ngừng hoạt động hoàn toàn.

Kết luận

Pine Script và server giao tiếp với nhau qua đúng một thứ là nội dung tin nhắn, nên thiết kế payload chính là thiết kế hợp đồng giữa hai nửa của hệ thống. Một payload gồm mã cặp, khung thời gian, hướng lệnh, giá tham chiếu và mã tín hiệu là đủ để bot hoạt động chính xác và đủ để bạn gỡ lỗi khi có sự cố.

Ba điều cần nhớ: dùng hàm alert với tần suất gửi khi nến đóng cho mọi tín hiệu đặt lệnh, không viết placeholder bên trong chuỗi Pine Script mà phải tự chuyển giá trị thành chuỗi, và luôn có mã tín hiệu để chống trùng.

Nếu bạn muốn viết được payload này cho cả MT5, Binance và chứng khoán Việt Nam trong một lộ trình có người hướng dẫn, hãy xem Bootcamp TradingView Webhook Bot của Hướng Nghiệp AI. Khoá học có bản ghi từng buổi và tặng kèm một buổi 1-1 để rà lại script và payload của riêng bạn.

Đọc tiếp trong chuỗi: TradingView Webhook Bot là gì, cách tạo alert TradingView gửi webhook và nhận webhook TradingView bằng Python.