商户入门:从注册到第一次在线聊天
希望 AI 直接帮你实现?复制 网站在线客服提示词,配合本指南在你的项目中开发。
也可以逐步完成:每节末尾展开 让 AI 完成本步骤,复制其中的提示词到已打开网站项目的 AI 编程助手。每个提示词都可独立使用;填写项目资料即可,不要填入密钥或密码。配置未确认时只做本地模拟,真实联调和生产发布需另外授权。
完成本教程后,您的网站用户可以发送咨询,您的客服可以在 Open4X 工作台回复。第一轮只接通文字人工客服,不依赖 AI、Telegram 或商户工单同步。
适用对象:新注册商户、负责接待的运营人员,以及负责网站接入的开发人员。最后核对日期:2026-09-14。
::: important 开始前请了解 当前是低代码接入,不是纯后台配置:商户需要一个安全的服务端 Session 接口,再加载网页聊天组件。只把脚本粘贴到页面、只注册 Open4X 账号,或者只创建 Bot Service,都不能代替这些步骤。
功能部署与商户验收是两回事。以下操作必须在您的账号和网站上实际测试,不能把其他租户的测试结果当作自己的验收结果。 :::
1. 准备账号与网站信息
打开 注册页面,完成注册后登录 控制台。已有账号可直接登录。
| 准备内容 | 负责人 | 注意事项 |
|---|---|---|
| Open4X 注册邮箱、商户名称 | 商户 | 不提供密码 |
| 网站域名、测试页面地址 | 商户 | 接入页面应使用 HTTPS |
| 网站技术栈、开发联系人 | 开发人员 | 例如 React、Vue、WordPress、普通 HTML |
| 用户登录方式和稳定用户 ID | 开发人员 | Open4X 商户账号与网站用户账号是两套身份 |
| 接待人员及接待时间 | 商户 | 第一轮可由账号所有者接待 |
| 故障备用入口 | 商户 | 保留原工单、联系表单或其他联系方式 |
第一轮优先接入已登录的网站用户。匿名访客需要商户服务端生成可验证的匿名会话,不能让浏览器随意指定他人的用户 ID。
打开 Conversation Hub。新账号尚无会话时显示空列表是正常的,不代表必须购买 AI 或先绑定 Telegram。
让 AI 完成本步骤:整理网站接入资料
请检查当前网站项目,为接入 Open4X 人工客服整理准备清单,不修改业务代码。
参考:https://docs.open4x.com/zh/guide/merchant-chat-quickstart
识别技术栈、后端部署方式、登录实现、稳定用户 ID 来源、客服入口位置、现有工单或备用联系方式。区分网站用户身份与 Open4X 商户账号。
输出已从代码确认的资料及需商户填写的域名、环境、接待人员、接入负责人。标注依据文件,不猜测未知配置。若只有静态前端,说明需要安全后端签发 Session,不能把 Bridge Key 放进页面。
不读取或打印秘密,不代替商户注册或创建账号,不进行真实外部调用。缺少项目访问权限时,请我提供不含秘密的目录和技术栈信息。2. 确认接入环境
以下是正式环境配置;使用前由双方确认该商户允许在哪个环境测试。
| 配置 | 正式地址 |
|---|---|
| 控制台 | https://console.open4x.com |
| 会话工作台 | https://console.open4x.com/dashboard/conversations |
| API Base URL | https://api.open4x.com |
| Widget 页面 | https://widget.open4x.com |
| Widget Loader | https://widget.open4x.com/widget.js |
如果交付的是 staging 账号,必须使用交付包中的 staging Key、API、Console 和 Widget 全套配置,不得混用生产地址。域名无法访问时先联系接入负责人处理,不能自行换成另一个环境。
本教程使用 Conversation Hub,不使用旧版 /v1/apps/bot/... Session 接口。基础网页接待不需要先创建 Telegram Bot 或配置 AI 模型。
让 AI 完成本步骤:检查环境配置
请为当前项目检查 Open4X 在线客服的环境配置,只做配置准备,不发送真实消息或部署。
参考:https://docs.open4x.com/zh/guide/merchant-chat-quickstart
目标环境:[本地 / 已授权 staging / 已授权生产测试;默认待确认]
根据项目惯例整理 API、Console、Widget 和 Loader 配置,并生成不含秘密的示例。生产 API 是 https://api.open4x.com;不能把它当作 staging 默认地址。staging 必须使用同一交付包的全套地址、租户和 Key,不自动回退到生产或 workers.dev。
检查前后端配置边界、HTTPS、现有 CSP/CORS 和部署配置,标注每个变量在哪配置、是否公开。只确认秘密是否已设置,不读取或打印值。未知环境列为阻塞项,提供本地 mock 配置并保留现有改动。3. 获取专用接入 Key
打开 API Keys。网页客服服务端需要一把独立 Bridge Key,至少包含:
conversation:read
conversation:write在 API Keys 页面 点击 Create New Key,填写名称,勾选 conversation:read 和 conversation:write,再点击 Create Key。权限默认不勾选,至少选择一项才能创建。需要管理事件 Webhook 或重放事件时,再额外勾选 conversation:events:write。bot:send 不能代替会话权限,不需要勾选与当前集成无关的权限。
已有 Key 的权限不会自动变化。请创建专用会话 Key,更新服务端配置并验证后,再按需撤销旧 Key。
请对接人员一并确认:所属租户、环境、Scope、有效期、每分钟限流、并发、每日配额、允许来源/IP 策略及费用上限。没有统一默认免费额度,实际以 Key 策略和商户约定为准。
Key 通过商定的安全渠道交付,优先直接写入商户服务端 Secrets。不要将完整 Key 发到普通聊天、工单正文、截图、代码仓库或浏览器。若限制 IP,应使用网站服务端的出口 IP,而不是访客 IP;网页域名白名单不能代替服务端密钥保护。
开发人员将以下配置保存在服务端:
OPEN4X_API_BASE=https://api.open4x.com
OPEN4X_BRIDGE_KEY=<通过安全渠道交付的密钥>不得使用 VITE_、NEXT_PUBLIC_ 等会进入前端构建的公开变量保存 Key。需要自有工单同步时再额外申请 conversation:events:write;基础网页聊天不需要 AI Scope,也不需要给浏览器 conversation:supervise。
服务端调用 GET /v1/conversations/credentials/status,请求头使用 Authorization: Bearer <Bridge Key>。确认返回的状态、Scope、到期时间和配额与交付包一致。此接口不返回完整密钥。
本步完成标志: 开发人员能用专用 Key 查询凭据状态;浏览器里没有该 Key。
让 AI 完成本步骤:安全配置 Bridge Key
请在当前项目准备 Open4X Bridge Key 的服务端配置和凭据状态检查。
参考:https://docs.open4x.com/zh/guide/merchant-chat-quickstart
规范:https://docs.open4x.com/openapi/open4x.openapi.json
先识别后端与部署方式。告诉我在 Console > API Keys 创建专用 Key,只勾选 conversation:read、conversation:write。只有要管理事件 Webhook/重放时才额外需要 conversation:events:write。
提供 OPEN4X_API_BASE 和 OPEN4X_BRIDGE_KEY 的占位示例、服务端 Secrets 配置步骤及忽略文件检查。不得放进 VITE_、NEXT_PUBLIC_、前端源码、日志或聊天,不打印现有秘密,不自动修改或吊销已有 Key。
按当前规范实现仅服务端使用的 GET /v1/conversations/credentials/status 检查,使用 Bearer 请求头;不创建公开的凭据诊断接口。只有确认环境并授权后才执行,未配置时用 mock 测试。输出状态、Scope、过期和额度等非秘密信息,保留脱敏 request_id。
输出配置位置、检查代码、测试结果和待确认项。不要通过放宽权限或取消来源限制修复 403。4. 开发一个网站 Session 接口
先按接入端与身份合同确定当前入口:个人咨询、分组客服和商户管理员使用不同 Session。需要 AI 检查现有后端时,复制个人端检查提示词或客服端检查提示词,不要只按账号最高权限为所有页面签发同一种 Token。
在商户自己的网站实现 POST /api/open4x/session。这是商户接口,不是 Open4X 已经托管好的地址。下列 API 示例供开发人员实现此接口时使用,不能直接从浏览器携带 Bridge Key 调用。
该接口必须验证网站登录态、执行商户的 CSRF/来源校验及限流,再从服务端取得用户 ID 和显示名。以下示例中的 site-user-123 是占位符;不得把它固定用于所有访客。
4.1 创建或复用会话
向 POST https://api.open4x.com/v1/conversations 发送:
{
"external_conversation_id": "website:support:site-user-123",
"conversation_type": "general_support",
"participants": [
{
"external_participant_id": "site-user-123",
"role": "customer",
"display_name": "网站用户"
},
{
"external_participant_id": "merchant-support",
"role": "support_agent",
"display_name": "商户客服"
}
]
}这是“一位用户一条普通咨询会话”的示例命名规则。同一租户中保留稳定的业务 ID,以便刷新或换设备后复用。多站点应增加站点前缀;独立新工单应使用新的业务工单 ID,不要每次刷新随机创建。
从响应 data 中取得会话 id 及 participants。按外部 ID、角色和 status: active 精确找到用户及客服参与者,保存返回的 Open4X 参与者 ID。任一参与者不存在、重复匹配或已停用,都应停止签发,而不是回退到广播。
4.2 签发用户的短期令牌
向 POST /v1/conversations/{会话id}/widget-session 发送:
{
"external_user_id": "site-user-123",
"user_name": "网站用户",
"participant_id": "<响应中的用户参与者id>",
"recipient_participant_ids": ["<响应中的客服参与者id>"],
"ttl_seconds": 1800
}参与者 ID 必须使用上一步的响应,不能填 site-user-123 或自行拼接。商户服务端确定角色和收件人,不能信任浏览器直接传入的这类字段。
将 Open4X 返回的 data.session_token 和 data.expires_in 返回给当前网站用户;可采用以下商户响应格式:
{
"data": {
"session_token": "<短期令牌>",
"expires_in": 1800
}
}设置 Cache-Control: no-store。不要在共享 HTML 缓存中复用某位用户的令牌,也不要把令牌写入日志。有效期支持 900–3600 秒;到期后重新验证网站登录态,再签发新令牌。用户退出或切换账号时销毁旧组件,不复用上一用户的会话。
本步完成标志: 已登录用户能获得自己的短期令牌,未登录或无权访问者不能获得令牌。最小闭环可以复用现有用户数据,不强制新增 Open4X 专用数据库表。
让 AI 完成本步骤:开发完整 Session 接口
请在当前网站项目实现受保护的 POST /api/open4x/session,完成代码和自动化测试,不只是给出示例。这是商户自己的接口,不是 Open4X 托管接口。
项目资料:
- 技术栈及登录方式:[从当前项目识别]
- 网站/站点标识:[填写稳定标识]
- 场景:[默认已登录用户的一般客服咨询]
- 环境:[默认本地 mock;真实环境待确认]
先读取当前项目的鉴权和后端约定,保留已有改动,核对:
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
https://docs.open4x.com/zh/guide/conversation-hub
https://docs.open4x.com/openapi/open4x.openapi.json
文档不可读或字段冲突时列为阻塞项,不猜接口,不混用旧版 /v1/apps/bot Session API。
实现:
1. 验证真实网站登录态、CSRF/Origin 和限流。用户 ID、显示名、角色、收件人由服务端确定;拒绝浏览器伪造身份或访问其他人的订单/会话。订单场景先校验订单权限。
2. OPEN4X_BRIDGE_KEY 仅在服务端,通过 Bearer 调用,最小 Scope 为 conversation:read、conversation:write。不索要、打印或写入前端密钥,配置缺失时安全失败。
3. POST /v1/conversations 创建或复用会话。external_conversation_id 使用稳定站点前缀和实际用户/工单标识,不在刷新时随机生成,不把示例用户 ID 用于所有人。
4. 从响应 data.participants 按外部 ID、角色、活动状态精确匹配客户与客服,使用返回的 Open4X 参与者 ID。缺失、歧义或停用时停止;绝不回退广播。
5. POST /v1/conversations/{id}/widget-session,固定 participant_id 和 recipient_participant_ids,ttl_seconds 默认 1800,限制在 900–3600。只向当前用户返回 data.session_token、data.expires_in,响应 Cache-Control: no-store,日志不记录 token。
6. 过期时重新检查网站登录态后签发;不编造刷新 API。按接口实际合同处理超时、401/403、409、429、5xx。未知结果的写请求不盲目重试。保留脱敏 request_id,失败不阻断登录、订单或支付。
7. 复用现有用户数据,不无故增加数据库表。若业务确需持久化,说明必要性并提供迁移和回滚。
测试未登录、伪造身份、两用户隔离、稳定会话 ID、参与者缺失/歧义/停用、TTL、no-store、日志脱敏、上游失败及限流。Mock 不当作 staging 或生产验收。未明确授权不调用真实 Provider、不发布生产。
交付实际修改、配置示例、测试结果、商户端请求/响应示例及未验证项。现在开始检查和实现。5. 网页加载聊天组件
需要让用户重新进入多个历史会话?另见 Widget 用户会话列表,包含消息摘要、未读数和已读回执。该扩展已部署至正式域名,需商户接入用户列表 Session;本节仍是单会话接入。
对于服务端渲染的 HTML 页面,可在签发令牌后安全填入以下标签。下面的令牌占位符不能直接使用,必须由服务端进行正确的 HTML 属性转义:
<script
src="https://widget.open4x.com/widget.js"
data-token="服务端动态签发的Session Token"
data-widget-url="https://widget.open4x.com"
data-gateway-url="https://api.open4x.com">
</script>React、Vue 或其他单页网站应先调用自己的 Session 接口,再初始化组件。需要组件封装时,从对接人员处取得已确认版本及校验值的 SDK 交付包,参照开发者接入指南。不要假设公共 npm 包已经发布,也不要把本地 preview 版本当作生产交付版本。
如果网站设置 CSP,应允许 Widget Loader 的脚本来源与 Widget iframe 来源;connect-src 按实际发起请求的页面配置 API 的 HTTPS/WSS 来源。不要为接入而全局放开 * 或关闭 CSP。跨域调用商户自己的 Session 接口时,还需正确配置商户自己的 CORS、Cookie 和 CSRF 策略。
本步完成标志: 页面出现聊天入口,能打开对话并发送测试文字,网络请求中没有 Bridge Key。固定资产版本、SRI 校验值与兼容范围须由交付包确认,不能凭 widget.js 文件名推断为固定版本。
让 AI 完成本步骤:接入网站聊天组件
请在当前网站接入 Open4X Widget,复用现有页面风格和登录状态,完成代码及浏览器测试。
参考:
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
https://docs.open4x.com/zh/guide/support-integration
前置条件:商户自己的 POST /api/open4x/session 已实现并只返回当前用户短期 token。若未完成,请先说明缺口,不从浏览器直接用 Bridge Key 请求 Open4X。
先确认当前交付的 Loader/SDK 版本和实际初始化、销毁协议。不要猜 npm 包或 SDK 方法;没有协议时列为阻塞项。生产 https://widget.open4x.com/widget.js 不等于固定版本文件,不能虚构 SRI。
实现页面挂载、打开聊天、加载失败/重试和备用联系入口;避免重复挂载。组件只接收短期 token,不持久化到 localStorage 或日志。SSR 插入属性必须安全转义;SPA 从受保护的商户 Session 接口获取 token。
按实际协议处理过期重新鉴权、退出、账号切换和卸载;禁止复用上一个用户的组件或异步返回的旧 token。检查 API/Widget/Key 环境一致性及 HTTPS、CSP、CORS、Cookie、CSRF,不放开全部来源。
测试桌面与手机、重复挂载、Session 失败、退出/切换账户、token 过期、网络故障回退,确认浏览器无 Bridge Key。真实发送与部署需另行授权,mock 结果单独标注。交付代码、配置步骤、截图与测试结果。6. 在工作台接待并回复
- 网站用户发送一条消息,例如“你好,我想咨询”。
- 商户登录 Conversation Hub,确认当前账号/团队与接入 Key 属于同一租户。
- 打开对应会话,点击 Join/加入。需要独占客服处理时使用 Take over/接管。
- 选择 Public reply/公开回复 和具体用户收件人,输入文字并发送。
- 回到用户网站,确认回复显示在原会话中。
- 若曾接管,处理完毕后点击 Release/释放。关闭浏览器不会自动释放。
不要用 Internal note/内部备注 回复用户。公开回复默认选择具体参与者,不能把“所有参与者”当作多方私聊隔离。托管管理员工作台当前约每 3 秒增量同步消息,不是零延迟或送达 SLA。
第一轮可由商户账号所有者接待。增加同事时,使用团队成员及独立角色,不共享密码。conversation:supervise 是租户级监管权限,可查看全部会话及内部备注,不能授予普通网站用户或作者。详见管理员文档。
让 AI 完成本步骤:准备客服接待演练
请根据当前项目和官方文档生成本商户的人工客服接待演练单,不另建不必要的客服后台。
参考:https://docs.open4x.com/zh/guide/merchant-chat-quickstart
参考:https://docs.open4x.com/zh/guide/conversation-administration
工作台:https://console.open4x.com/dashboard/conversations
演练核对同一租户/环境、网站测试用户发起咨询、客服 Join、选择具体收件人并公开回复、网站原会话收到回复、内部备注不出现在用户端,以及 Take over 后 Release。
使用商户所有者或已授权的独立客服账号,不共享密码,不给网站用户 conversation:supervise。多方会话不得默认所有参与者互见。按文档说明按钮含义和失败时的排查步骤,不虚构客服角色或菜单。
输出可填写的演练表、会话 ID/request_id 记录位置及未配置项。默认只准备步骤;执行真实发送前确认环境、测试账号和授权。没有实测不要勾选通过,不收集密码、完整 token 或真实客户正文。7. 按表验收后开放给客户
| 测试 | 通过标准 |
|---|---|
| 网站发送、工作台回复 | 双向文字都出现在同一会话,收件人正确 |
| 页面刷新、用户重新登录 | 按商户业务规则恢复原会话,不重复创建 |
| 短暂断网后恢复 | 历史可补拉,不重复展示同一消息 |
| 两个不同用户咨询 | 不能看到或回复对方会话 |
| 内部备注 | 仅授权工作台可见,用户网页不出现 |
| Token 到期、退出和切换账号 | 重新鉴权或关闭旧组件,不串号 |
| Open4X 不可用 | 网站登录、订单、支付不受阻,仍有备用联系入口 |
| AI 关闭 | 全部基础人工流程正常,不向模型发送数据 |
记录测试日期、双方人员、环境、会话 ID、异常 request_id 及结论。截图请脱敏,不包含完整 Token、Key、订单隐私或真实客户正文。页面 HTTP 200 或 API 健康检查不能代替这张验收表。
让 AI 完成本步骤:编写并运行验收测试
请独立检查当前网站的 Open4X 聊天接入,为下列验收项补充并运行本地测试:
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
https://docs.open4x.com/openapi/open4x.openapi.json
覆盖网站发送/客服回复、刷新恢复、断线续传不重复、两用户隔离、内部备注隔离、token 过期/退出/切换账号、Open4X 故障不影响登录订单支付,以及 AI 关闭时完整人工流程。
复用现有测试工具,使用 mock 模拟不安全或会产生费用的请求。对只能通过真实 Widget/Provider 验证的项目给出演练脚本,未授权不执行外发消息或生产发布。不可把 mock 或 HTTP 200 当作真实闭环证据。
检查当前实现是否真正在服务端授权和控制收件人,而非仅隐藏前端按钮。输出问题及文件位置、实际命令和测试结果、未执行原因、脱敏证据记录模板。区分本地、staging、生产,结论为可继续联调/阻塞/可申请生产验收,不自动宣布上线。8. 常见问题
按实际出问题的入口复制检查提示词:个人端 / 网站客服 / 商户管理员与控制台 / 加载、来源与版本。让 AI 返回脱敏诊断记录,区分已确认根因与待验证假设。
| 现象 | 排查方向 |
|---|---|
| Key 页面没有会话权限 | 确认打开正式 Console 并强制刷新;按第 3 步创建专用 Key,Bot Scope 不等价 |
| 工作台没有会话 | 确认 Session 接口确实创建了会话,并核对环境、租户和列表筛选 |
| 个人端出现接收人或内部备注 | 检查是否误发 wbs_、入口身份解析或旧凭证缓存;不能仅隐藏按钮 |
| 同 tag 的用户/订单未进客服列表 | 核对客服 scope: groups、实际 group_tags、每个会话的 support_group/support-routing、用户默认组和会话覆盖组;metadata.tag 不授权 |
| 工作台提示权限不足 | 检查当前团队角色;普通参与者不能访问租户级监管页面 |
| 回复按钮不可用 | 检查是否已加入、是否填写内容、同步是否异常、是否被其他管理员接管;发送公开回复还需选择收件人 |
| 返回 401/403 | 区分商户登录态、Bridge Key 权限/来源、Widget Token 到期,不要改用全权限 Key |
| 返回 409 | 核对幂等键是否复用了不同内容,以及接管版本是否过期;不要无限重试 |
| 返回 429 | 查看实际 Key 的限流、并发和每日配额,按 Retry-After 退避;没有自动不限额承诺 |
| 跨域或组件空白 | 检查商户 Session 接口、三个环境地址、HTTPS、Cookie、CSP 和控制台报错;不要暴露 Key 到前端绕过 |
| 刷新后变成新会话 | 检查是否每次随机生成 external_conversation_id,或用户 ID 不稳定 |
让 AI 完成本步骤:排查当前接入错误
请排查当前网站的 Open4X 接入问题,先定位再做最小修复。
现象:[填写,例如 Session 返回 403、Widget 空白或收不到回复]
发生环境和时间:[填写]
脱敏 request_id/状态码/控制台错误:[填写,不包含 Key、Cookie、token 或客户正文]
参考:https://docs.open4x.com/zh/guide/merchant-chat-quickstart
从浏览器→商户 Session 后端→Open4X→Widget/工作台逐层检查,区分网站登录、Key Scope/来源、token 过期、租户/环境、参与者/收件人、接管状态、限流和 CSP/CORS。
先阅读相关代码及非秘密配置,只检查秘密是否存在,不输出值。文档与实际响应不一致时记录证据,不猜接口。不把 403 改成全权限,不关闭授权/CSP,不暴露 Key,不无限重试 409 或 429,不切换环境绕过问题。
给出根因证据、最小改动、针对性回归测试和待验证项。没有项目或日志访问权限时只请求必要的脱敏信息。真实外发和生产部署另行确认。9. 交付确认清单
请商户与对接人员逐项填写;未填写项不视为已承诺:
- 商户注册邮箱、租户/团队、接入负责人:待确认。
- 正式或 staging 环境,以及 API、Console、Widget 地址:待确认。
- 专用 Key 的安全交付方式、Scope、到期时间、IP 策略:待确认,不记录完整密钥。
- 限流、并发、每日配额、费用上限及告警方式:待确认。
- SDK/Loader 版本、校验值、支持的浏览器范围:待确认。
- 网站 Session 接口负责人、部署位置、故障备用入口:待确认。
- 首次接待人员、验收日期、上述测试结论:待确认。
- 数据保留、删除方式、服务区域、DPA、价格及 SLA:按商户合同确认。
需要订单咨询时,在上述闭环通过后扩展 order_support 和订单权限校验;需要自有工单同步时再实现 Webhook、持久化去重、outbox 与对账。Telegram、附件、多方会话和 AI 均应单独验收,不作为本教程已完成的隐含能力。
相关资料:开发者接入指南 · 会话 API · 管理员操作 · OpenAPI。
让 AI 完成本步骤:生成商户交付记录
请根据当前项目、实际测试证据和以下清单生成商户 Open4X 聊天接入交付记录:
https://docs.open4x.com/zh/guide/merchant-chat-quickstart
包含租户/环境及地址、配置项名称与部署位置、Scope/期限/额度/费用上限、SDK 版本校验值、Session 实现位置、客服操作、故障回退、验收结果和回滚步骤。只记录秘密的配置状态,不写完整值。
每项标注已确认、待商户确认或未验证,并附证据来源;无法从项目确认的额度、价格、SLA、DPA、数据保留或服务区域不得编造。区分 mock、staging、生产测试,不因代码完成就宣称商户验收通过。
未接入的 Telegram、附件、AI、多方会话或工单同步列为不在本次范围。不修改生产、不新增权限、不替商户批准上线。交付一份便于商户签收的记录和剩余事项清单。