文档中心

了解 whatzsay 是什么、如何开始使用、如何接入你的网站。

一、whatzsay 是什么？

whatzsay 是一个面向网站的智能客服系统。把客服窗口嵌入你的网站后，访客可以随时提问：AI 结合你配置的 FAQ 与大模型即时应答，复杂问题一键转交人工坐席，全部会话在管理台集中处理。

• AI 即时应答 —— LLM 结合自定义 FAQ 秒级回复，平台兜底模型保障可用性
• 人工接待与路由 —— 访客可随时转人工，系统按轮询/ least-busy 规则自动分配坐席
• 图片 / 语音消息 —— 粘贴或选择图片、一键录制语音，双向即时可见
• 注册客户 —— 邮箱注册 + 邮件激活，历史会话跨设备跟随
• 多租户 · 多站点 —— 站点、团队、坐席独立管理，数据严格隔离
• 统计与成本控制 —— AI 会话统计、LLM 用量与平台兜底额度一目了然

二、快速开始

只需四步，即可让你的网站拥有智能客服：

1. 登录管理控制台（/admin/），在「站点管理」选择或新建站点，获取站点 Key（ck_ 开头）。
2. 在「站点管理 → AI 配置」开启 AI 助手：配置欢迎语与模型参数；在「FAQ 管理」维护常见问答，命中即秒回。
3. 在「用户管理」添加坐席账号并组建团队，访客转人工时自动按规则分配。
4. 按下方「集成指南」把客服窗口接入网站，或先在本站首页体验访客视角。

管理台角色：Owner（租户管理员，拥有全部权限）、Admin（站点管理）、Agent（客服坐席，负责接待会话）。

三、集成指南

目前提供两种接入方式；访客页开箱即用，无需开发。

方式一：iframe 嵌入（推荐，无需开发）

将下面代码粘贴到你网站的页面里（建议放在 body 末尾），并把 YOUR_SITE_KEY 替换为你的站点 Key：

<!-- whatzsay 客服组件 -->
<iframe src="https://whatzsay.com/test/web?site=YOUR_SITE_KEY"
        style="position:fixed;right:20px;bottom:20px;width:380px;height:560px;
               border:0;border-radius:16px;box-shadow:0 12px 40px rgba(0,0,0,.18);
               z-index:9999" allow="clipboard-write"></iframe>

• 宽度、高度与位置可通过 style 任意调整；去掉定位样式即可作为整页客服页使用。
• 移动端访客页为 /test/mobile?site=…，适合手机端体验或作为单独入口。
• iframe 内即完整访客端：支持 AI / 人工通道、图片与语音消息、送达与已读回执。

方式二：HTTP API（自定义 UI）

所有请求需携带请求头 X-Site-Key 标识站点，业务请求再携带 Authorization: Bearer <token>；基础路径为 /chat/api/v1/widget。

示例：初始化访客并获取访问令牌

curl -X POST https://whatzsay.com/chat/api/v1/widget/init \
  -H "X-Site-Key: YOUR_SITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"zh-CN"}'

• token 用于后续请求的 Authorization 头；visitor_key 请持久保存，可用于找回历史会话。
• 限速：init 5 次/分钟/IP，发消息 10 次/60 秒/访客，超限返回 429。
• 消息拉取建议用 after_id 增量轮询（约 1.5~5 秒间隔），只拉取新消息。
• 富媒体消息：先 POST /chat/api/v1/upload 上传附件（multipart 字段 file；图片 ≤5MB 支持 png/jpg/jpeg/gif/webp，语音 ≤10MB 支持 webm/ogg/mp4/m4a/mp3/aac），再把返回的 /chat/uploads/… URL 作为 content、content_type 设为 image 或 audio 发送。访客端组件支持一键录制语音（单条 ≤5 分钟）。

四、常见问题