Hành động: câu trả lời từ chính hệ thống của bạn

Hành động cho phép bot của bạn tra cứu điều gì đó trong chính hệ thống của bạn ngay giữa cuộc trò chuyện — đơn hàng đang ở đâu, khi nào được giao, lượt đặt chỗ đã được xác nhận chưa. Khách hàng hỏi, bot thu thập những gì cần thiết, gọi API của bạn, và trả lời dựa trên kết quả nhận về, bằng ngôn ngữ của khách hàng.

Nó hoạt động ở mọi nơi bot của bạn hoạt động: tiện ích trang web, liên kết bot và mã QR của bạn, cùng các ứng dụng Android, iOS, React Native, Flutter và Ionic. Không cần cài đặt hay cập nhật gì — lệnh gọi được thực hiện từ máy chủ của chúng tôi, nên thông tin xác thực API của bạn không bao giờ đến trình duyệt hay điện thoại.

Trước khi bắt đầu: bất kỳ ai cũng có thể trò chuyện với bot của bạn

Bot của bạn là một kênh trò chuyện công khai. Nếu chỉ cần mã đơn hàng là đủ để xem đơn, bất kỳ ai cũng có thể gõ thử các số cho đến khi trúng một mã.

Bot hỗ trợ theo ba cách, nhưng không cách nào thay thế được bước kiểm tra đó: nó chỉ gửi các giá trị mà khách hàng thực sự đã nhập, nó giới hạn số lượt tra cứu mà một cuộc trò chuyện hoặc một địa chỉ có thể thực hiện, và bạn có thể chọn những trường nào của phản hồi mà nó được phép thấy.

Thiết lập một hành động

Mở Hành động trong bảng điều khiển và chọn Hành động mới. Chủ sở hữu và quản trị viên có thể thấy màn hình này.

• Tên — dành cho bạn, chẳng hạn "Trạng thái đơn hàng".
• Khi nào bot nên dùng nó? — một câu, như cách bạn nói với đồng nghiệp mới: "Khách hàng hỏi đơn hàng của họ đang ở đâu hoặc khi nào sẽ đến."
• Địa chỉ API của bạn — GET hoặc POST, và một địa chỉ https://. Viết {{order_id}} vào chỗ cần điền giá trị.
• Những gì bot hỏi khách hàng — tối đa sáu giá trị. Mỗi giá trị có một nhãn theo cách nói của bạn ("Mã đơn hàng"), tên mà API của bạn dùng (order_id) và một kiểu: văn bản bất kỳ, một con số, một địa chỉ email hoặc một số điện thoại.
• Header — khóa API hoặc token của bạn. Được lưu trữ mã hóa và không bao giờ hiển thị lại.
• Chỉ chia sẻ các trường này với bot — tùy chọn. Liệt kê các phần của phản hồi mà bot được phép dùng, chẳng hạn status, eta, items[].name. Mọi thứ khác sẽ bị loại bỏ trước khi AI nhìn thấy.

Nhấn Kiểm tra, nhập các giá trị mẫu, và bạn sẽ thấy yêu cầu đã gửi cùng chính xác những gì bot sẽ nhận được. Sau đó thử thật trên màn hình Kiểm tra: "Đơn hàng 48213 của tôi đang ở đâu? Email của tôi là asha@example.com".

API của bạn nhận được gì

Với GET, các giá trị bạn đặt trong địa chỉ sẽ được điền vào, phần còn lại được thêm vào chuỗi truy vấn:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Với POST, các giá trị nằm trong phần thân JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Mỗi yêu cầu cũng mang theo các header của riêng bạn và những header sau:

Gửi lại những gì

Phản hồi trong vòng 8 giây bằng JSON, hoặc một dòng văn bản thuần ngắn.

• 200 kèm dữ liệu — bot sẽ trả lời từ đó. Giữ phản hồi gọn và dùng tên trường rõ ràng: {"status":"shipped","eta":"2 October"} hiệu quả hơn các mã nội bộ.
• 404 khi không có gì khớp — bot sẽ báo cho khách hàng và đề nghị họ kiểm tra lại những gì đã nhập.
• Bất kỳ trường hợp nào khác, hoặc không phản hồi kịp — bot sẽ xin lỗi, đưa ra thông tin liên hệ của bạn, và cuộc trò chuyện được đánh dấu cho bạn. Lý do được hiển thị trên màn hình Hành động.

Chuyển hướng không được theo, và phản hồi lớn hơn 256 KB sẽ không được đọc.

Kiểm tra chữ ký

Các yêu cầu được ký theo cách của Standard Webhooks, nên bạn có thể dùng một thư viện sẵn có. Khóa ký bí mật của bạn nằm trên màn hình Hành động.

Thủ công: nối id, dấu thời gian và phần thân chính xác bằng dấu chấm, ký chuỗi đó bằng HMAC-SHA256 với khóa bí mật (phần sau whsec_, đã giải mã base64), rồi so sánh.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Với yêu cầu GET, phần thân trống nên chuỗi được ký kết thúc bằng dấu chấm. Hãy dùng POST nếu bạn muốn chính các giá trị cũng được chữ ký bao phủ.

Cách bot sử dụng

• Nó hỏi bất cứ thông tin nào còn thiếu, mỗi lần một câu hỏi ngắn, và ghi nhớ những gì khách hàng đã nói trước đó trong cuộc trò chuyện.
• Nó không bao giờ đoán giá trị. Nếu khách hàng chưa nhập, bot sẽ hỏi.
• Mỗi tin nhắn một lượt tra cứu. Các câu trả lời đã lưu của bạn vẫn được ưu tiên trước, nên câu hỏi bạn đã tự trả lời sẽ không bao giờ gọi API của bạn.
• Câu trả lời từ một lượt tra cứu không bao giờ được dùng lại cho khách hàng khác.
• Một lượt tra cứu được tính là một câu trả lời, giống như mọi phản hồi khác do AI viết.

Trong Trò chuyện, câu trả lời đến từ một lượt tra cứu sẽ được ghi chú bên dưới: hành động nào đã chạy và kết quả ra sao. Các giá trị khách hàng đã nhập chỉ nằm trong bản ghi cuộc trò chuyện và không ở đâu khác.

Giới hạn

Hành động chỉ đọc thông tin. Đừng trỏ hành động đến một địa chỉ làm thay đổi dữ liệu — hủy đơn hàng hay hoàn tiền cần một bước xác nhận mà bot hiện chưa có.