Visitor API

​

1. Đọc cấu hình hiển thị

GET https://agents.fpt.ai/direct-bff/v1/visitor/config?connectionKey=wgt_abc123

{
  "name": "Acme Support",
  "avatarUrl": "https://…/logo.png",
  "theme": { "primary": "#203BDC", "position": "right" },
  "welcome": { "title": "Xin chào!", "subtitle": "Chúng tôi có thể giúp gì?" },
  "starters": ["Theo dõi đơn hàng", "Đổi trả", "Liên hệ nhân viên"],
  "turnstileSitekey": "0x4AAA…",
  "locales": ["vi", "en", "ja", "id", "zh"],
  "localeDefault": "vi",
  "chat": {
    "placeholder": "",
    "disclaimer": "Nội dung do AI tạo, vui lòng kiểm chứng.",
    "poweredBy": "Powered by FPT.AI",
    "showLogoHeader": true,
    "showCitations": true,
    "allowAttachments": true
  }
}

• turnstileSitekey, avatarUrl và localeDefault trả về null khi chưa đặt, không bao giờ là chuỗi rỗng. Một turnstileSitekey rỗng sẽ bật cổng chống bot mà không khách hàng nào qua được.
• chat luôn là một đối tượng, không bao giờ null. Ba giá trị đúng/sai trong đó luôn có mặt và mặc định là bật.
• chat.placeholder rỗng nghĩa là tổ chức không tự soạn; hãy dùng chuỗi đã dịch sẵn của bạn.
• theme và welcome được trả về nguyên trạng, không kiểm tra định dạng. Hãy tự kiểm tra trước khi đưa vào CSS.
• Danh sách tên miền cho phép không nằm trong kết quả và không chi phối lệnh này; nó được áp dụng ở lệnh tạo phiên.

​

2. Tạo phiên

POST https://agents.fpt.ai/direct-bff/v1/visitor/session
Content-Type: application/json
Origin: https://shop.example.com

{
  "connectionKey": "wgt_abc123",
  "locale": "vi",
  "visitorToken": "eyJ…",
  "visitorName": "Nguyễn Văn An",
  "turnstileToken": "0.abc…"
}

{
  "visitorToken": "eyJ…",
  "expiresAt": "2026-09-14T10:00:00Z",
  "sessionId": "7412",
  "endUserId": "9876"
}

• visitorToken sống 1 giờ. Gửi nó ở header Authorization: Bearer cho mọi lệnh gọi sau đó.
• sessionId là định danh hội thoại, giữ nguyên qua các lần kết nối lại.
• Tất cả định danh số nguyên đều là chuỗi trên đường truyền, vì chúng vượt ngưỡng số nguyên an toàn của JavaScript.

​

Khách hàng quay lại

​

3. Mở luồng nhận trả lời

GET https://agents.fpt.ai/direct-bff/v1/sessions/7412/stream
Authorization: Bearer <visitorToken>
Accept: text/event-stream

​

4. Gửi một tin nhắn

POST https://agents.fpt.ai/direct-bff/v1/runs
Authorization: Bearer <visitorToken>
Content-Type: application/json

{
  "sessionId": "7412",
  "agentId": "5",
  "input": "Đơn hàng của tôi đang ở đâu?",
  "metadata": { "postback": "order:list" },
  "attachments": [
    {
      "objectKey": "ws/1/channels/42/7412/9f3c….pdf",
      "name": "bao-gia.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 184320
    }
  ]
}

• metadata là một đối tượng đóng: chỉ postback được đọc, mọi khóa khác bị bỏ qua.
• workspaceId, connectionId, endUserId và userId không được nhận trong phần thân vì đều lấy từ token. Gửi kèm bất kỳ trường nào sẽ nhận 400 WORKSPACE_ID_NOT_ACCEPTED; giá trị null tường minh được coi như không gửi. Riêng sessionId vẫn hợp lệ và được đối chiếu với token.
• Phần thân tối đa 256 KiB.
• Tối đa 5 tệp đính kèm trên một lượt gửi; tệp thứ sáu bị từ chối bằng 400 INVALID_ARGUMENT. Hãy kiểm tra số lượng ở phía giao diện trước khi tải lên.

​

5. Tải tệp đính kèm lên

POST https://agents.fpt.ai/direct-bff/v1/visitor/uploads
Authorization: Bearer <visitorToken>
Content-Type: multipart/form-data

file=<nội dung tệp>

{
  "objectKey": "ws/1/channels/42/7412/9f3c….pdf",
  "name": "bao-gia.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 184320
}

• Một tệp cho mỗi lần gọi, tối đa 30 MiB.
• Phần mở rộng được chấp nhận: pdf, doc, docx, ppt, pptx, jpg, jpeg, png, gif, svg, webp, heic, jfif, xlsx, xls, csv.
• Phần mở rộng và các byte đầu tệp đều được kiểm tra. Tệp thực thi đổi tên thành .png sẽ bị từ chối bằng 415.
• Không nhận workspaceId, sessionId hay connectionId trong form; tất cả lấy từ token.

​

6. Tải tệp do Agent tạo ra

POST https://agents.fpt.ai/direct-bff/v1/visitor/files/presign
Authorization: Bearer <visitorToken hoặc khóa API>
Content-Type: application/json

{ "objectKey": "ws/1/artifacts/7311064883817021440/bao-cao.pdf", "disposition": "attachment" }

{ "url": "https://…", "expiresInSeconds": 300 }

• disposition quyết định tệp được tải về hay mở ra. Dùng attachment cho mọi đường dẫn bạn định điều hướng tới; dùng inline (mặc định) cho đường dẫn đặt vào thẻ img hoặc tải ngầm. Tệp lưu dưới dạng text/html sẽ hiển thị như một trang web khi trình duyệt điều hướng tới, thay thế luôn khung chat của khách hàng.
• Đường dẫn sống 300 giây và được cấp mới mỗi lần gọi. Đừng lưu lại, hãy xin lại khi cần.
• visitorToken chỉ đổi được tệp do chính hội thoại của họ tạo ra. Khóa API đổi được mọi tệp trong tổ chức của mình.
• 404 cho cả tệp không tồn tại lẫn tệp không thuộc quyền, cố ý dùng chung một mã để không ai dò được tệp nào đang tồn tại.

​

7. Đánh giá một câu trả lời

POST https://agents.fpt.ai/direct-bff/v1/visitor/feedback
Authorization: Bearer <visitorToken>

{ "messageId": "01J…", "rating": "up", "comment": "" }

• messageId là mã tin nhắn AG-UI mà giao diện của bạn đã hiển thị, không phải mã số nội bộ.
• comment là tùy chọn và bị cắt ở 2000 ký tự chứ không bị từ chối.
• Không có đường đọc ngược: nếu muốn giữ trạng thái nút thích sau khi tải lại trang, hãy tự nhớ ở phía giao diện.