开发者文档

阅读网站 Embed、Flutter Customer SDK 和企业工作台的接入与使用指南。

安全提示：企业接入密钥只保存在宿主后端。请勿将密钥、访问令牌或客户资料写入客户端、日志或错误报告。

开始使用

GreenChat 提供什么

网站与 Flutter App 可分别提供客户聊天入口。企业客服在统一工作台接待授权渠道的会话。客户聊天与员工登录分别使用独立的认证流程。

申请、审核与开通

提交企业申请并保存回执码。平台管理员审核后，将开通指引写入状态查询。按指引确认首任负责人，平台侧完成企业登记、激活与负责人配置后，再登录企业工作台。

申请开通

设置员工与渠道

企业负责人在企业工作台的员工管理添加或邀请客服，在接入渠道创建网站或 App 渠道，再用分配员工为客服授权接待。已有账户可能需要先接受邀请。

网站 Embed

创建 Web 渠道并授权来源

在企业工作台打开接入渠道，新增网站渠道。填写完整来源（协议、主机和非默认端口），为需要使用的子域分别授权。配置网站自己的同源签票路径并启用 Embed。生成脚本和公开接入标识位于渠道的接入配置。

加载渠道生成的脚本

将工作台生成的脚本加到受信任的网站页面。下方地址和路径展示配置格式，实际以渠道生成内容为准。公开接入标识不是服务端密钥。

HTML

<!-- Copy the generated snippet from your web channel. -->
<script async
  src="https://chat.greenchat.cn/embed/v1/loader.js"
  data-site="REPLACE_WITH_48_HEX_PUBLIC_KEY"
  data-bootstrap="/greenchat/bootstrap"></script>

宿主后端签发票据

Loader 向 data-bootstrap 指向的同源地址发送 JSON POST，包含 challenge、purpose 和可选 source_page_url。宿主后端根据受信任配置和访问策略验证来源与用户，必要时配置身份，然后调用以下 GreenChat 接口。source_origin 必须来自受信任配置，不能由浏览器任意指定。签票成功后返回 JSON 中的 ticket 和 purpose（create 或 resume），并设置 Cache-Control: no-store。接入密钥只保存在宿主服务端。

HTTP

POST /api/v1/integration/sites/{publicKey}/embed-tickets
Authorization: Bearer <server-only intake key>
Content-Type: application/json

{
  "challenge": "<64 lowercase hex characters from the loader>",
  "purpose": "create",
  "source_origin": "https://your-site.example"
}

配置 CSP 并发送测试消息

允许聊天域加载脚本和 loader.css，并允许对应 frame-src。宿主页的 connect-src 需要允许同源签票请求。若响应缺少聊天框对当前站点的 frame-ancestors 授权，检查渠道允许来源及实际代理配置。在真实 HTTPS 域名打开聊天按钮，发一条测试消息并在工作台认领、回复和重开页面验证。

Flutter Customer SDK

安装与平台要求

当前仓库包为 0.1.0 私有包，支持 Android 和 iOS。最低 Dart 3.8、Flutter 3.32。使用经授权的仓库路径或锁定的私有 Git 提交，然后执行 flutter pub get。Android 声明 INTERNET，iOS 图片选择需配置 NSPhotoLibraryUsageDescription。

YAML

dependencies:
  greenchat_customer_sdk:
    path: ../support-center/packages/greenchat_customer_sdk

在后端为已登录客户获取票据

在 App 渠道创建客户集成。宿主后端必须用自己的会话确认客户身份，从该会话派生稳定的 external_user_id。GreenChatAuthRequest.toJson() 提供 client_instance_id、code_challenge、purpose，宿主后端将它们转发到票据 API。把 ticket 和 integration_id 返回给客户端；客户端通过 GreenChatTicket.fromJson 解析。集成密钥和服务端凭证严禁放入 Flutter、JavaScript 或其他客户端。

HTTP

POST /api/v1/integration/customer-integrations/{integration}/tickets
Authorization: Bearer <server-only customer integration key>
Content-Type: application/json

{
  "external_user_id": "<stable ID from your verified host session>",
  "client_instance_id": "<from GreenChatAuthRequest>",
  "code_challenge": "<from GreenChatAuthRequest>",
  "purpose": "customer.authenticate"
}

初始化并打开聊天

在应用初始化 Flutter binding 后，创建一个 GreenChatClient。宿主的 authProvider 需提供有限请求超时并转发 request.cancelled。SDK 在 /api/v1/customer-identity/exchange 完成票据交换；会话凭证在内存中。将 GreenChatChatPage 放在有边界的布局中，可用 GreenChatLocale.zhCN 显示中文。打开默认聊天页不会立即创建咨询。

Dart

import 'package:flutter/material.dart';
import 'package:greenchat_customer_sdk/greenchat_customer_sdk.dart';

// Supply your application's authenticated backend adapter as hostTicketProvider.
GreenChatClient createSupportClient(GreenChatAuthProvider hostTicketProvider) {
  return GreenChatClient(GreenChatConfiguration(
    apiBaseUri: Uri.parse('https://api.greenchat.cn/api'),
    authProvider: hostTicketProvider,
  ));
}

Widget supportScreen(GreenChatClient client) => Scaffold(
  body: GreenChatChatPage(client: client, locale: GreenChatLocale.zhCN),
);

发送消息与读取历史

默认聊天页面可发送文字和 JPEG、PNG、WebP 图片，并显示身份关联的连续会话。自定义界面可使用 history、messages 与 sendText。示例中的 consultationId 来自当前身份有权访问的咨询。

Dart

final history = await client.history(limit: 20);
final operation = client.prepareText(consultationId, 'Hello support');
await client.sendText(operation); // Reuse operation if the result is uncertain.
final page = await client.messages(consultationId, afterId: 0);

登录、退出与切换用户

宿主登录后可 await client.authenticate()，或让聊天页自动认证。宿主退出时 await client.logout() 并清理宿主登录态。换账号时更新宿主登录信息，通过 client.switchIdentity(authProvider: nextProvider) 重置 SDK 身份。不要复用上一身份的草稿、图片或操作对象。

客服工作台与员工 App

登录和接待

用获授权的员工账号登录企业工作台并选择企业。打开待接待队列，在授权渠道认领咨询。发送文字或支持的图片，可在有权限时查看客户资料和历史。历史非图片附件能否打开取决于客户端和访问权限。

转接、结束和重新接待

在会话中选择符合接待条件的同事发起转接，根据操作提示确认。完成服务后结束会话。需要继续时在已结束队列打开咨询，按权限重新接待。

移动接待与通知

使用企业提供的 Android 或 iOS GreenChat 员工 App，以授权账号登录，选择企业后处理客户咨询。前台更新和后台推送依赖客户端版本、服务端设置和设备权限。Android 推送使用 FCM，iOS 推送使用 APNs。

故障排查

入口缺失或来源被拒绝

核对 web 渠道已启用、脚本路径与 data-site 值正确，查看浏览器网络和 CSP 错误。完整来源的协议、域名和端口必须匹配。检查脚本、样式和聊天框是否被代理或扩展拦截。

认证失败、401、403 或 429

401 通常表示缺少、过期或撤销的凭证，按客户端流程获取新凭证。403 检查域名、企业和渠道权限，以及集成状态。票据失败时重新签发并检查实例 ID、challenge 和用途。遇到 429 等待 Retry-After。

消息不更新或后台没有通知

确认当前会话、企业和网络。SDK 仅在界面前台可见时轮询，支持实时更新的工作台可以在连接失败后轮询。后台推送请检查 FCM/APNs 凭证与设备注册、系统通知权限和省电限制。

联系我们