Biến AI Action

Ở mọi vị trí nhập giá trị trong API Action (URL, header, nội dung hoặc tham số truy vấn), bạn có thể chèn giá trị động bằng cú pháp {{...}}. Quickchat thay placeholder ngay trước khi gọi endpoint.

Nhấp + Thêm dữ liệu AI cạnh trường giá trị để xem mọi biến có trong scenario hiện tại.

Nút + Thêm dữ liệu AI có cạnh mọi trường giá trị: URL endpoint, header, trường nội dung và tham số truy vấn.

Công cụ thiết lập tùy chọn

• Xem trước yêu cầu API Action. Hiển thị mẫu yêu cầu bằng giá trị mẫu tổng hợp mà không gửi. Bỏ header chứa thông tin xác thực.

• Xem trước khóa siêu dữ liệu. Kiểm tra tên trường trở thành khóa biến thế nào, gồm tên trùng và lỗi khóa dành riêng. Không kiểm tra giá trị hoặc quyền riêng theo tài khoản.

Ba loại biến

Loại	Cú pháp	Khi nào được điền
Tham số AI: giá trị AI Agent trích xuất từ đối thoại. Định nghĩa trong phần Tham số của từng Action.	{{order_number}}, {{customer_email}}	AI Agent điền lúc gọi theo quy tắc trong mô tả tham số.
Biến có sẵn: ngữ cảnh Quickchat tự chèn.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Luôn có. Quickchat thay trong mỗi yêu cầu.
Siêu dữ liệu cuộc trò chuyện: cặp khóa-giá trị tùy chỉnh gắn vào đối thoại.	{{metadata_<key>}}	Khi khóa tương ứng tồn tại, do widget, tích hợp kênh, Thu thập dữ liệu thông minh hoặc API đặt.

Mẹo

Mỗi biến được hiển thị như thẻ màu trong trình sửa. Xanh dương là tham số AI hoặc biến có sẵn. Cam là siêu dữ liệu hoặc token hệ thống. Đỏ là tên Quickchat không nhận diện (thường do gõ sai).

Danh sách “+ Thêm dữ liệu AI”

Danh sách chứa mọi biến khả dụng trong scenario, chia năm phần:

1. Tham số: tham số AI định nghĩa trên Action.
2. Khách truy cập: bốn khóa siêu dữ liệu tự lấy cho khách khi kênh cung cấp.
3. Metadata (đã dùng trong hội thoại gần đây): khóa tùy chỉnh thấy trong 20 cuộc gần nhất, kèm giá trị mẫu.
4. Có sẵn: bảy biến luôn có, hiển thị giá trị hiện tại hoặc mẫu bên cạnh.
5. Token hệ thống: thông tin xác thực do tích hợp kết nối cung cấp (ví dụ HubSpot, Telegram). Chỉ hiện khi kết nối. Xem Token hệ thống bên dưới.

Danh sách nhóm biến theo phần. Có sẵn hiện giá trị thực nếu đã biết (scenario_id), còn lại hiện mẫu e.g. …. Metadata (đã dùng trong hội thoại gần đây) dựng lại theo từng scenario từ đối thoại thực gần đây. Token hệ thống (không hiện ở đây) chỉ xuất hiện khi tích hợp kết nối.

Ghi chú

Danh sách Metadata (đã dùng trong hội thoại gần đây) dựng từ 20 cuộc gần nhất và cache 5 phút cho mỗi AI Agent. Khóa đặt trong đối thoại mới có thể mất tới 5 phút để xuất hiện. Bạn luôn có thể gõ trực tiếp {{metadata_<your_key>}}; Quickchat không yêu cầu khóa hiện trong danh sách để thay thế được.

Biến có sẵn

Bảy biến này luôn khả dụng. Danh sách + Thêm dữ liệu AI hiện giá trị thực (nếu đã biết) hoặc mẫu cạnh từng hàng.

Biến	Ví dụ	Ý nghĩa
{{scenario_id}}	abc123xyz	ID AI Agent mà đối thoại thuộc về.
{{conversation_id}}	conv-d8a8…	Định danh duy nhất của đối thoại.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Liên kết trực tiếp tới cuộc trò chuyện trong Hộp thư đến.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Kênh đối thoại đang diễn ra.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Ngày giờ UTC hiện tại theo ISO 8601.
{{language}}	en, nl, de, fr, …	Mã ngôn ngữ cuộc trò chuyện ISO 639-1 chữ thường.
{{country}}	US, GB, NL, DE, …	Mã quốc gia ISO 3166-1 alpha-2 chữ hoa.

Một số điểm cần biết:

• {{scenario_id}} cũng có trong URL trình duyệt khi sửa Action. Danh sách + Thêm dữ liệu AI hiện ID thực của scenario đang sửa, không phải mẫu.
• {{conversation_url}} hữu ích để đăng liên kết vào Slack, Jira hay công cụ cần quay thẳng về Hộp thư đến.
• {{language}} được suy ra theo thứ tự: tiền tố URL trang (cho Shopify Markets), siêu dữ liệu, rồi ngôn ngữ cấu hình của Agent.
• {{country}} được suy ra theo thứ tự: tiền tố URL, TLD hostname, rồi phương án dự phòng từ ngôn ngữ sang quốc gia.

Siêu dữ liệu cuộc trò chuyện

Bắt buộc có tiền tố metadata_. Quickchat tìm <key> trong siêu dữ liệu rồi thay giá trị vào yêu cầu.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Khóa siêu dữ liệu khách truy cập

Bốn khóa mô tả phiên khách và có phần Khách truy cập riêng. Chúng có thể lấy từ kênh, tích hợp, widget/nhúng, API, Thu thập dữ liệu thông minh hoặc ánh xạ đầu vào Action đã cấu hình.

Biến	Tự thu thập bởi
{{metadata_fullPathURL}}	Widget website, bản nhúng hoặc tích hợp chat có widget riêng (HubSpot, Intercom, v.v.).
{{metadata_visitor_name}}	Hồ sơ kênh (Telegram, Slack, v.v.), tích hợp, Thu thập dữ liệu thông minh, ánh xạ đầu vào Action, widget/nhúng của bạn hoặc Quickchat API.
{{metadata_visitor_email}}	Hồ sơ kênh, tích hợp, Thu thập dữ liệu thông minh, ánh xạ đầu vào Action, widget/nhúng của bạn hoặc Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp và kênh biết số điện thoại, tích hợp, Thu thập dữ liệu thông minh, ánh xạ đầu vào Action, widget/nhúng hoặc Quickchat API.

Khóa siêu dữ liệu tùy chỉnh

Bạn có thể gắn cặp khóa-giá trị bất kỳ vào đối thoại và tham chiếu bằng {{metadata_<key>}}.

Từ widget hoặc bản nhúng website

Truyền custom_params khi khởi tạo widget. Xem Kênh website: Tính năng nâng cao: Tham số tùy chỉnh để có đoạn mã đầy đủ.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Tham chiếu trong bất kỳ Action bằng {{metadata_order_id}} và {{metadata_customer_tier}}.

Chú ý

Khóa phải khớp ^[a-zA-Z0-9_]+$ (chữ, số, gạch dưới). Khóa có khoảng trắng hoặc dấu khác không thể dùng qua {{metadata_<key>}}. Chúng vẫn hiện trong siêu dữ liệu Hộp thư đến nhưng bị bỏ khi thay Action. Dùng snake_case nếu định sử dụng trong Actions.

Từ Thu thập dữ liệu thông minh

Mỗi mục bật trong Thu thập dữ liệu thông minh trở thành khóa theo tên ở dạng snake_case chữ thường: khoảng trắng thành gạch dưới, bỏ dấu và dấu câu khác.

Mục dữ liệu	Biến
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

Liên hệ là ngoại lệ. Mục tên Email, Name, Phone number (hoặc biến thể tiếng Anh gần như Email address, Full name, Mobile) điền {{metadata_visitor_email}}, {{metadata_visitor_name}}, {{metadata_visitor_phone_number}}. Chỉ nhận tên tiếng Anh: Correo electrónico thành khóa riêng correo_electronico. Khi AI lấy liên hệ chưa có trong đối thoại, nó cũng đặt lead_captured là true.

• Trống đến khi thu thập. Khóa thêm với giá trị rỗng khi AI trả lời lần đầu với tính năng bật, rồi điền khi khách cung cấp. Sửa sau sẽ cập nhật; không bị làm rỗng lại.
• Dùng is true để chờ giá trị. Trong Chạy khi, budget is true qua khi có giá trị, còn budget exists qua ngay khi tính năng đã chạy. Câu trả lời như no, false, 0 tính là sai.
• Giá trị bạn đặt được ưu tiên. Nếu khóa đã có giá trị do website, API hay Action khác đặt, tính năng không đổi. Nó cũng ngừng cập nhật khi nguồn khác sửa khóa.
• Một số tên dành riêng, như language, locale, lead_captured. Mục có tên đó không thành biến; hãy đổi tên nếu cần.
• Đổi tên mục cũng đổi biến. Cập nhật Actions dùng nó: Action không chạy được khi thiếu biến cần thiết.

Khi đối thoại có khóa, khóa cũng xuất hiện trong + Thêm dữ liệu AI.

Kiểm tra điều kiện chạy Action trên siêu dữ liệu mẫu để biết điều kiện nào qua. Phép kiểm tra đánh giá giá trị cung cấp mà không chạy Action.

Từ đầu vào hoặc phản hồi Action

API Action có thể lưu đầu vào khai báo hoặc giá trị phản hồi API vào khóa để Action sau dùng lại. Trong Lưu vào bộ nhớ, chọn Đầu vào của Action hoặc Phản hồi API làm Nguồn. Với Giá trị cần lưu, chọn tham số từ danh sách cho đầu vào hoặc nhập JSONPath cho phản hồi, rồi chọn Khóa bộ nhớ. Tham chiếu bằng {{metadata_<memory key>}}.

Ánh xạ đầu vào tới visitor_name, visitor_phone_number, visitor_email cũng điền liên hệ chưa đặt trong Hộp thư đến. Giá trị hiện có và trường nhân viên đã xóa rõ ràng được giữ. Đầu vào lưu trước yêu cầu HTTP sau khi vượt kiểm tra, nên liên hệ hợp lệ vẫn còn khi API lỗi. Xem Lưu vào bộ nhớ để biết ví dụ và hướng dẫn đầy đủ.

Từ tích hợp kênh

HubSpot, Intercom, Telegram, Slack, WhatsApp và tích hợp tương tự đẩy siêu dữ liệu riêng vào đối thoại (tên khách, email, URL trang, thuộc tính tài khoản, v.v.). Mọi thứ thấy trong siêu dữ liệu Hộp thư đến đều có thể tham chiếu bằng {{metadata_<key>}}.

Từ Quickchat API

Dùng POST /v1/api_core/conversations/{conv_id}/metadata để gắn bằng lập trình. Xem Siêu dữ liệu cuộc trò chuyện trong tài liệu API.

Token hệ thống

Một số tích hợp cung cấp token hệ thống: thông tin xác thực Quickchat chèn vào yêu cầu phía máy chủ, lúc gọi khi Action chạy. Token không thêm vào ngữ cảnh AI hay siêu dữ liệu, và bị che trong nhật ký yêu cầu, trace, nhật ký gọi Hộp thư đến. Siêu dữ liệu thường không có bảo đảm bí mật tương tự. Token chỉ xuất hiện trong phần Token hệ thống của + Thêm dữ liệu AI khi đúng tích hợp được kết nối, dưới dạng thẻ cam.

Token hệ thống	Khả dụng khi	Giá trị chèn
{{hubspot_access_token}}	Đã kết nối HubSpot	Token truy cập OAuth HubSpot hợp lệ, tự gia hạn.
{{telegram_bot_token}}	Scenario có hoạt động Telegram	Token bot Telegram kết nối để gọi Telegram Bot API.

Gọi Telegram Bot API

Telegram Bot API nhận token trong đường dẫn URL nên tham chiếu trực tiếp ở URL endpoint:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

Quickchat điền token lúc gọi và che ở mọi nơi hiển thị yêu cầu để không lộ bí mật. Để gọi cho chat, tin nhắn hoặc người gửi hiện tại, kết hợp các khóa Quickchat đặt trên mỗi tin Telegram đến:

Khóa siêu dữ liệu	Giá trị
{{metadata_telegram_chat_id}}	Chat nguồn của tin nhắn.
{{metadata_telegram_chat_type}}	private, group, supergroup hoặc channel.
{{metadata_telegram_user_id}}	ID Telegram của người gửi.
{{metadata_telegram_username}}	@username người gửi nếu có.
{{metadata_telegram_message_id}}	ID tin nhắn đến.
{{metadata_telegram_sender_is_admin}}	true khi người gửi là quản trị chat. Tính phía máy chủ nên không giả mạo từ chat được. Dùng trong điều kiện chạy để chỉ quản trị viên thực hiện kiểm duyệt.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Đặt khi tin đến là phản hồi để AI xử lý tin được trả lời (ví dụ kiểm duyệt tác giả).

Màu thẻ trong trình sửa

Mỗi tham chiếu {{...}} hiện như thẻ màu để biết ngay Quickchat có nhận diện biến không.

Thẻ hoạt động trong mọi trường giá trị. Trên: {{metadata_user_type}} cam trong URL và {{language}} xanh ở header.

Quy tắc màu tương tự trong JSON. Biến có sẵn như {{country}} màu xanh, siêu dữ liệu như {{metadata_fullPathURL}} màu cam.

• 🔵 Xanh dương: biến có sẵn hoặc tham số AI bạn định nghĩa.
• 🟠 Cam: biến siêu dữ liệu ({{metadata_*}}) hoặc Token hệ thống từ tích hợp.
• 🔴 Đỏ: Quickchat không nhận tên. Gần như luôn do gõ sai. Sửa chính tả, định nghĩa tham số AI hoặc nếu là khóa siêu dữ liệu thì bảo đảm bắt đầu metadata_.

Mẹo

Gõ trực tiếp {{metadata_anything}} luôn hợp lệ dù khóa chưa xuất hiện ở đối thoại nào. Thẻ cam, không đỏ. Đây là cách nối khóa bạn tự đặt từ script widget hoặc Thu thập dữ liệu thông minh trước cuộc đầu tiên.

Kiểm thử Action

Bảng Kiểm thử phản hồi (cạnh Xong trong trình sửa) gửi HTTP thực mà không qua chat. Mỗi biến tham chiếu có hàng để điền giá trị Quickchat sẽ thay.

Bảng điền sẵn biến có sẵn bằng ngữ cảnh thực hoặc mẫu đại diện. Mặc định ngôn ngữ, thời gian gồm:

• {{language}} mặc định en
• {{country}} mặc định US
• {{current_timestamp}} mặc định giờ UTC hiện tại

Ghi đè bất kỳ trường để thử giá trị khác. Tham số AI và {{metadata_*}} ban đầu trống. Nhập giá trị bất kỳ để mô phỏng đối thoại thực.

Câu hỏi thường gặp

Vì sao biến màu đỏ? Trình sửa không nhận tên: gõ sai, không khớp tham số AI, không phải biến có sẵn hoặc khóa siêu dữ liệu thiếu tiền tố metadata_.

Có chèn {{language}}, {{country}} dù chưa đặt không? Có. Quickchat luôn suy ra từ ngữ cảnh (URL trang, ngôn ngữ trình duyệt hoặc cấu hình Agent). Luôn nhận được giá trị, kể cả dự phòng en / US.

Khác nhau giữa {{language}} và {{metadata_locale}}?

• {{language}} có sẵn, luôn khả dụng, luôn dạng en / nl / de … Dùng trong 99% trường hợp.
• {{metadata_locale}} chỉ có nếu tích hợp hoặc widget đặt rõ khóa locale trong siêu dữ liệu, thường dạng xx_YY (ví dụ en_GB). Chỉ dùng khi cần nguyên văn chuỗi locale chính xác.

Có giới hạn tham số AI mỗi Action không? Có, 30 mỗi Action. Nếu cần hơn, liên hệ hỗ trợ.

Giá trị có sẵn và siêu dữ liệu có gửi tới AI không? Quickchat thay giá trị khi tạo HTTP; AI không cần sinh hoặc định nghĩa thành tham số. Với Action AI quyết định, thay sau khi AI chọn Action. Action tự động không yêu cầu AI chọn.

Thay thế và ngữ cảnh mô hình là riêng biệt. Siêu dữ liệu đủ điều kiện và ngữ cảnh có sẵn cũng có thể được cấp cho AI; phản hồi Action có thể chứa cùng giá trị. Siêu dữ liệu khác được lọc khỏi prompt. Đừng giả định siêu dữ liệu thường luôn hiển thị hoặc luôn ẩn. Xem Ngữ cảnh mô hình và phân quyền.

Danh sách “Metadata (đã dùng trong hội thoại gần đây)” làm mới bao lâu? Cache 5 phút mỗi Agent. Khóa ở cuộc mới có thể mất tới 5 phút để hiện, nhưng luôn gõ trực tiếp {{metadata_<your_key>}} mà không chờ được.

Tên khóa phân biệt hoa thường không? Có. {{metadata_orderId}} và {{metadata_orderid}} khác nhau. Dùng đúng kiểu chữ đặt ở widget, tích hợp hoặc API.

Bảng Kiểm thử phản hồi biết các biến này không? Có. Bảng điền sẵn cả bảy biến, gồm {{language}} là en, {{country}} là US, {{current_timestamp}} là giờ UTC hiện tại. Tham số AI và siêu dữ liệu bắt đầu trống. Nhập giá trị để mô phỏng gọi thực.

Liên quan

• Actions tùy chỉnh: tạo và cấu hình API Action.
• Kênh website: Tham số tùy chỉnh: đưa siêu dữ liệu từ website.
• API: Siêu dữ liệu cuộc trò chuyện: đưa dữ liệu bằng lập trình.