第一步：创建 API 客户端

在左侧表单中填写名称、允许来源（官网域名）、限流值后点击创建。Key 仅显示一次，请立即复制保存。

浮窗接入必须填"允许来源"——填入官网完整域名（如 https://www.example.com），支持多个用逗号分隔。服务端调用可以不填来源。

第二步：配置 CORS

在服务器 .env 中，把相同域名加入 CORS_ALLOWED_ORIGINS：

CORS_ALLOWED_ORIGINS=https://www.example.com

第三步：复制基础代码到官网

把以下代码粘贴到官网每个页面的 </body> 之前。JSON 配置提供入口图片、业务场景和开场快捷词等默认值；每个官网必须填写唯一的来源站点标识，供会话和线索归因。

<script
  src="https://您的服务域名/static/widget.js"
  data-config-url="https://您的服务域名/static/widget-configs/land-main.json"
  data-source-site="land-main"></script>

将 data-source-site 改为当前官网唯一标识，例如第二个征地拆迁官网填写 land-second。下一节选择与官网业务对应的配置地址即可。专题页或投放页需要例外配置时，可在同一个标签上补写少量 data-* 属性覆盖 JSON 默认值。JSON 配置只能保存公开的前端展示和会话字段，不能填写管理密钥或其他敏感信息；图片地址可写公网绝对地址或相对配置文件的路径。跨域部署时，仍须把官网域名加入 CORS_ALLOWED_ORIGINS。

如需在官网顶部导航栏额外增加“在线咨询”按钮，可在按钮上添加 data-sa-open-widget，它会打开同一个咨询窗口，不替代右下角入口。

<button type="button" data-sa-open-widget>在线咨询</button>

入口图片在对应的 JSON 配置中维护。图片地址可使用公网绝对地址，或相对配置文件的路径；换图只需更新配置文件，不必更新官网页面。

第四步：选择业务配置

将第三步中的 data-config-url 替换为下列对应业务的一行。每份配置文件包含业务场景和开场快捷词等默认值；同一业务场景下的多个官网可共用一份配置，并各自填写不同的 data-source-site。只有默认入口图片、话术或主题需要长期分开维护时，才新增配置文件。

data-config-url="https://您的服务域名/static/widget-configs/land-main.json"

data-config-url="https://您的服务域名/static/widget-configs/criminal-defense-official.json"

data-config-url="https://您的服务域名/static/widget-configs/marriage-family.json"

data-config-url="https://您的服务域名/static/widget-configs/debt-dispute.json"

data-config-url="https://您的服务域名/static/widget-configs/contract-dispute.json"

data-config-url="https://您的服务域名/static/widget-configs/labor-dispute.json"

第五步：页面覆盖配置（按需）

新官网先在第三步填写唯一的 data-source-site，不必新建 JSON 文件。专题页、投放页或活动页与业务默认值不同时，保留 data-config-url，只补写有差异的其他 data-* 属性。页面上显式填写的值优先于 JSON 中的同名配置。

<script
  src="https://您的服务域名/static/widget.js"
  data-config-url="https://您的服务域名/static/widget-configs/land-main.json"
  data-source-site="land-compensation-topic"
  data-starter-prompts="补偿方案不合理怎么办？,协议还没签,已经强拆"
  data-launcher-image-url="https://您的官网域名/assets/compensation-consult.png"></script>

常见可覆盖项包括业务场景、来源站点、开场快捷词、入口图片、主题色和欢迎语；未填写的字段继续使用 JSON 默认值。

内联配置项（页面覆盖与兼容已有接入）

新官网默认不需要逐项填写下列 data-* 属性；使用 JSON 配置时，只按需填写需要覆盖的字段。已使用旧接入代码的官网也可继续保留这些字段。

场景选择与页面覆盖（data-scene-code）

远程 JSON 配置已经包含默认场景码，无需在官网页面重复填写。业务专题页可补写 data-scene-code 覆盖默认值；完全不填写时，系统根据访客消息自动识别场景。data-source-site 始终由官网页面填写，不在业务 JSON 配置中维护。

data-scene-code 只负责选择业务场景，不会自动替换开场快捷词，也不能区分两个同场景官网。需要区分来源时，同时调整 data-source-site；需要不同开场词时，再调整 data-starter-prompts。

服务端直接调用接口

适合官网后端、CRM 或其他系统调用，需要在请求头携带 API Key，路由为 /api/chat（不是 widget）。scene_code 可留空自动识别。

POST /api/chat
Content-Type: application/json
X-API-Key: sa_xxx

{
  "visitor_id": "web-user-001",
  "session_id": null,
  "scene_code": "land_expropriation",
  "message": "拆迁补偿太低怎么办？"
}

返回结果

前端优先展示 messages 数组，可以按顺序分气泡显示；reply 用于兼容只支持单条文本的旧页面。

{
  "session_id": 123,
  "scene": "land_expropriation",
  "reply": "兼容旧接入的完整回复",
  "messages": [
    {
      "content": "您遇到的是土地征收、房屋拆迁还是厂房征收？",
      "buttons": [
        {"label": "土地征收", "value": "土地征收"},
        {"label": "房屋拆迁", "value": "房屋拆迁"},
        {"label": "厂房征收", "value": "厂房征收"}
      ]
    }
  ],
  "knowledge_source_mode": "external",
  "direct_answer": false
}