Thay thế và công thức

Thay thế là các biến dạng {{...}}, được chèn vào văn bản tin nhắn, trường hành động và template nút khi phản ứng kích hoạt. Các thay thế không nhận dạng được sẽ giữ nguyên. Ngoài biến, còn có công thức để tính toán. Nút «Thay thế» trong trình chỉnh sửa tin nhắn giúp chèn biến.

Dữ liệu người gửi

  • {{first_name}}, {{last_name}} — tên và họ.
  • {{username}} — @username của người dùng.
  • {{user_id}} — Telegram ID dạng số.

Dữ liệu sự kiện và cuộc trò chuyện

  • {{text}} (còn gọi là {{received_message}}) — văn bản tin nhắn đến.
  • {{message_id}} (còn gọi là {{received_message_id}}) — ID tin nhắn đến.
  • {{chat_id}}, {{chat_title}} (còn gọi là {{chat_name}}) — cuộc trò chuyện nơi sự kiện xảy ra.
  • {{topic_id}}, {{topic_url}} — chủ đề (cho forum).

Ngày và giờ

  • {{date}} — ngày (YYYY-MM-DD), {{time}} — giờ (HH:MM), {{datetime}} — ngày và giờ.
  • Định dạng: {{date:DD.MM.YYYY HH:mm}} — token YYYY, YY, MM, DD, HH, mm, ss.

Tham số người dùng

  • {{param.key}} (còn gọi là {{params.key}} hoặc {{recipient.key}}) — giá trị tham số của người đăng ký. Tham số được điền bởi các hành động «Thay đổi tham số», «Lưu tin nhắn» và phản hồi trong hội thoại.

Ngữ cảnh thực thi (ctx)

  • {{ctx.key}} (còn gọi là {{context.key}}) — các giá trị tạm thời của lần chạy hiện tại: dữ liệu webhook đến, kết quả hành động (yêu cầu web, truy vấn nguồn, AI), dữ liệu nút đã khôi phục (Carry), phần tử vòng lặp.
  • Trong vòng lặp danh sách phần tử được truy cập bằng bí danh của nó, ví dụ {{item.name}}.

Công thức

Cấu trúc {{= biểu thức}} tính toán biểu thức ngay trong văn bản. Cùng một engine hoạt động trong hành động «Tính toán» và trong điều kiện của bảng quyết định. Trong biểu thức có thể tham chiếu tham số và giá trị ctx theo tên, sử dụng số học, so sánh, logic và hàng chục hàm tích hợp (ROUND, IF, CONCAT và nhiều hàm khác).

Ví dụ: {{= ROUND(param.total * 0.9) }} — giảm giá 10% từ tổng tiền trong tham số.

Cú pháp đầy đủ và danh sách hàm — trong mục Công thức.

HTML trong thay thế

Tin nhắn được gửi với markup HTML. Để giá trị được thay thế không phá vỡ bố cục (ví dụ khi tên người dùng chứa <), các giá trị thay thế mặc định được escape: các ký tự HTML trở thành văn bản an toàn. Các thẻ bạn viết trực tiếp trong văn bản phản ứng (<b>, <a>, …) được giữ nguyên.

Nếu bản thân giá trị đã chứa markup có sẵn (ví dụ một thông báo lưu trong tham số với <b>...</b>) và bạn muốn chèn nó nguyên trạng, hãy thêm tiền tố & trước thay thế:

  • {{& key}} — chèn thô cho các thay thế {{...}}.
  • {&user:key}, {&recipient:key}, {&global:key} — chèn thô cho các thay thế namespace.

Tiền tố & chỉ tắt escaping cho riêng thay thế đó — bạn chịu trách nhiệm về độ tin cậy của nguồn giá trị. Tốt nhất nên để các token do người đăng ký kiểm soát ({{first_name}}, …) ở trạng thái được escape.

Khi nhập bot từ các trình tạo khác, các thay thế namespace {user:…}/{recipient:…}/{global:…} được tự động chuyển sang dạng thô {&…} — chúng thường chứa các giá trị có markup sẵn, đúng như cách trình tạo nguồn hoạt động.

Lưu ý về định dạng

Thay thế {{...}} hoạt động trong văn bản, chú thích, thân yêu cầu và template nút. Đặt tên tham số và khóa ctx ngắn gọn và bằng ký tự Latin (email, total, order_id) — sẽ tiện hơn khi chèn vào.

Bước tiếp theo