开发者文档
从网页咨询，到持续接待
先选择正确入口，再接入正确能力：Widget 服务匿名网页访客，H5 服务登录后的移动会话，PC 工作台只提供给客服身份。
选择入口
- 网页 Widget：适合官网、帮助中心和业务页面，访客不注册即可咨询。
- H5 客服系统：适合登录后的移动端持续会话；注册需要商户邀请码，客服身份由商户后台配置。
- PC 客服工作台：适合桌面集中接待，只允许已配置客服身份的账号登录。
网页 Widget 快速接入
正式使用请在商户后台获取专属邀请码，并替换下方占位符。不要把官网演示邀请码部署到自己的页面。把代码放在页面底部、</body> 前即可。
index.html
<script
src="https://oaim.im/static/plug/js/oaim-widget.js?v=16"
data-invite-code="YOUR_INVITE_CODE"
data-position="right"
defer></script>SDK 会自动生成客服浮窗，不需要额外写 HTML。
参数说明
| 参数 | 必填 | 说明 | 示例 |
|---|---|---|---|
| data-invite-code | 必填 | 商户后台生成的专属邀请码，用于识别访客归属。 | YOUR_INVITE_CODE |
| data-title | 选填 | 无需填写。Widget 自动读取商户后台的标题。 | OAIM 在线客服 |
| data-position | 选填 | 浮窗位置，支持 right 或 left。 | right |
| data-base-url | 选填 | Widget 服务地址，默认自动取脚本域名。 | https://oaim.im |
| 当前页面地址 | 自动 | SDK 读取浏览器当前页面用于来源校验和客服参考，不支持用属性伪造覆盖。 | 浏览器 location.href |
商户配置
- 在商户后台设置 Widget 标题、欢迎语和快捷按钮。
- 设置自动弹窗、延迟弹窗，以及关闭后本次不再打开。
- 生产环境配置明确域名白名单；留空代表商户主动允许任意来源嵌入，可填写 oaim.im 或 *.oaim.im。
- 客服工作台会显示访客 IP、访问页面、来源域名、设备来源和访问时间。
H5 客服系统
H5 是登录后的移动会话入口，不是匿名网页浮窗。商户邀请码用于注册归属；普通用户和客服账号都可登录，客服身份由商户后台维护。
- 访问 H5 客服系统 登录或注册。
- 客服账号可在 H5 处理会话；同一人工账号在 H5 与 PC 再次登录会替换旧会话。
- 移动端支持文字、表情、图片、失败重试和新消息回到底部。
PC 客服工作台
PC 入口仅接受已配置客服身份的账号。普通用户不能通过 PC 登录；客服可查看会话、访客来源、设备、地区和访问页面。
- 入口：客服工作台。
- 新消息提醒、在线状态与未处理卡片由商户后台聊天设置控制。
- PC 静态资源有运行镜像，发布必须通过现有就绪检查。
安全与隐私
- Widget 通过浏览器来源和短期嵌入凭证校验，不接受用页面属性伪造来源。
- 嵌入方应告知访客：打开咨询会处理当前页面、设备和网络信息；页面地址不应包含密码、Token、订单敏感字段等。
- 商户启用 Telegram 离线通知或地区查询前，应阅读隐私说明并评估自身告知义务。
常见问题
Widget 没弹出来？
检查接入代码是否放在页面里、邀请码是否正确、当前域名是否在商户后台白名单内。
客服端看不到访问页面？
SDK 自动读取当前浏览器页面。确认接入页面在商户白名单内，再刷新客服端访客资料。
能不能只显示浮标，不自动弹窗？
自动弹窗及延迟统一由商户后台控制；修改后台设置后所有接入页面会按新配置读取。
H5 和 PC 能同时使用吗？
可以，但同一人工账号后一次登录会替换前一次会话。Widget 访客不受此规则影响。