青鸾派接入文档

青鸾派 · 开发者

接入文档

把青鸾派客服嵌进你的网站、App 或小程序。访客从哪来，对话都进同一个收件箱；答不了的问题，阿鸾会转给人工。

网页浮窗一行 script，三分钟上线 JS 接口设置用户、开关浮窗、监听事件 开放接口会话、消息、联系人

网页浮窗嵌入

在后台「设置 → 收件箱」创建网站渠道后，复制嵌入代码，放到页面 </body> 前：

<script
  src="https://kf.eggopc.com/widget/qingluan.js"
  data-token="你的收件箱标识"
  data-theme="auto"
  async></script>
属性说明
data-token必填。收件箱的网站渠道标识（Website Token）。
data-themeauto（默认）/ light / dark。
data-greeting可选。覆盖气泡问候语。
data-open设为 1 时页面加载后自动打开浮窗。
data-hide-brand设为 1 时隐藏底部品牌字样。
data-locale可选。访客语言：auto（跟随浏览器，默认）/ zh / en。也可在工作室「浮窗外观 → 访客语言」统一设置。

正式环境请始终使用 https://kf.eggopc.com。本地调试可用同一域名（已配置 CORS）。

JS 接口

脚本加载后会挂载 window.$qingluan（同时兼容 window.Qingluan）。文档只使用 $qingluan。

设置用户信息

window.$qingluan.setUser({
  id: "u_10086",           // 你的业务用户 ID（建议稳定不变）
  name: "王小明",
  email: "wang@example.com",
  phone: "13800000000",
  avatar: "https://example.com/a.png",
  identifier_hash: "HMAC签名" // 见下方「身份校验」
});

自定义属性

window.$qingluan.setCustomAttributes({
  plan: "团队版",
  company: "企鹅派",
  order_id: "SO-20261102"
});

访客语言

浮窗、联系页的访客可见文案支持中文与英文。后台与客服侧始终为中文。

// 运行时切换（也会写入本机记忆）
window.$qingluan.setLocale('en');   // 或 'zh' / 'auto'

嵌入时可用 data-locale="en"；工作室「浮窗外观」里的「访客语言」会对整个团队生效。英文访客提问时，阿鸾会用英文回答（知识库为中文时会翻译）。

打开 / 关闭浮窗

window.$qingluan.open();
window.$qingluan.close();
window.$qingluan.toggle();
console.log(window.$qingluan.isOpen());

事件监听

var off = window.$qingluan.on("ready", function () {
  console.log("浮窗就绪");
});
window.$qingluan.on("open", function () {});
window.$qingluan.on("close", function () {});
window.$qingluan.on("unread", function (n) {
  console.log("未读", n);
});
window.$qingluan.on("message", function (msg) {
  console.log("新消息", msg);
});
// 取消监听
off();
// 或
window.$qingluan.off("ready");

身份校验（HMAC）

防止访客伪造身份。在后台「设置 → 收件箱 → 网站渠道」开启「身份验证」后，用渠道密钥在服务端计算 HMAC-SHA256，再传给 setUser。

// Node.js
const crypto = require("crypto");
function identifierHash(userId, secret) {
  return crypto.createHmac("sha256", secret).update(String(userId)).digest("hex");
}
# Python
import hmac, hashlib
def identifier_hash(user_id: str, secret: str) -> str:
    return hmac.new(secret.encode(), str(user_id).encode(), hashlib.sha256).hexdigest()

密钥只放在服务端，绝不要写进前端代码或公开仓库。

在 App 里接入（通用说明）

App 内无需调用任何接口，直接用 WebView 打开以下任一地址即可，两者都已适配手机竖屏/横屏：

页面地址
全屏聊天页（推荐）https://kf.eggopc.com/widget/app.html?token=你的收件箱标识
联系页https://kf.eggopc.com/c/你的链接名

收件箱标识在后台「设置 → 收件箱 → 网站渠道 → 嵌入代码」里 data-token 的值。

iOS（WKWebView）

import WebKit

let web = WKWebView(frame: view.bounds)
web.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(web)
let url = URL(string: "https://kf.eggopc.com/widget/app.html?token=你的收件箱标识".addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!)!
web.load(URLRequest(url: url))

Android（WebView）

WebView web = findViewById(R.id.web);
web.getSettings().setJavaScriptEnabled(true);
web.getSettings().setDomStorageEnabled(true);
web.loadUrl("https://kf.eggopc.com/widget/app.html?token=你的收件箱标识");

Flutter（WebView）

import 'package:webview_flutter/webview_flutter.dart';

final controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..loadRequest(Uri.parse('https://kf.eggopc.com/widget/app.html?token=你的收件箱标识'));
// Widget 中：WebViewWidget(controller: controller)

React Native（WebView）

import { WebView } from 'react-native-webview';

export default function QingluanChat() {
  return (
    <WebView
      source={{ uri: 'https://kf.eggopc.com/widget/app.html?token=你的收件箱标识' }}
      javaScriptEnabled
      domStorageEnabled
    />
  );
}

微信小程序（web-view）

在小程序后台「开发管理 → 业务域名」添加 kf.eggopc.com，然后直接打开联系页或聊天页：

<!-- pages/chat/chat.wxml -->
<web-view src="https://kf.eggopc.com/c/你的链接名"></web-view>

联系页链接

在「青鸾工作室」创建联系页后，分享：

https://kf.eggopc.com/c/你的链接名

适合名片、海报、短信、邮件签名。打开即可直接聊天，无需再嵌浮窗。

转企业微信客服

  1. 在后台绑定企业微信应用（通知坐席、手机接待）。
  2. 访客在浮窗里说「转人工」或阿鸾判断需要人工时，会话会转给坐席，并推送企业微信卡片提醒。
  3. 坐席用企业微信打开接待页，或登录网页工作台继续回复。

阿鸾会附上对话摘要，减少坐席翻历史的时间。

开放接口

在后台「个人设置 → 访问令牌」创建令牌。请求头携带：

api_access_token: 你的访问令牌
Content-Type: application/json

基址：https://kf.eggopc.com。把路径里的 {account_id} 换成你的团队 ID（登录后可在个人资料接口看到）。

常用接口

方法路径说明
GET/api/v1/profile当前用户与所属团队
GET/api/v1/accounts/{account_id}/conversations会话列表
GET/api/v1/accounts/{account_id}/conversations/{id}/messages会话消息
POST/api/v1/accounts/{account_id}/conversations/{id}/messages发送消息
GET/api/v1/accounts/{account_id}/contacts联系人列表
POST/api/v1/accounts/{account_id}/contacts创建联系人

发送一条消息示例

curl -sS https://kf.eggopc.com/api/v1/accounts/1/conversations/123/messages \
  -H "api_access_token: 你的访问令牌" \
  -H "Content-Type: application/json" \
  -d '{"content":"你好，这是一条测试","message_type":"outgoing","private":false}'
import urllib.request, json
req = urllib.request.Request(
    "https://kf.eggopc.com/api/v1/profile",
    headers={"api_access_token": "你的访问令牌", "Accept": "application/json"},
)
print(json.load(urllib.request.urlopen(req)))

公开客户端接口（开放接口渠道）

需要自己画聊天界面时使用。它不使用网站浮窗的收件箱标识，而要单独建一个「开放接口」渠道：

  1. 后台「设置 → 收件箱 → 添加收件箱」，选择 API 类型（开放接口）。
  2. 创建后在该收件箱的「设置 → 配置」页复制 收件箱标识（Inbox Identifier）。

以下接口无需访问令牌，{inbox_identifier} 即上面复制的值：

方法路径说明
POST/public/api/v1/inboxes/{inbox_identifier}/contacts创建访客，返回 source_id
GET/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}读取访客
POST/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations创建会话
GET/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations会话列表
POST/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations/{conversation_id}/messages访客发消息
GET/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations/{conversation_id}/messages拉取消息
BASE=https://kf.eggopc.com/public/api/v1/inboxes/你的收件箱标识
# 1. 创建访客
curl -sS -X POST $BASE/contacts -H "Content-Type: application/json" \
  -d '{"identifier":"u_10086","name":"王小明"}'
# 返回 {"source_id":"...", ...}
# 2. 创建会话
curl -sS -X POST $BASE/contacts/SOURCE_ID/conversations -H "Content-Type: application/json" -d '{}'
# 返回 {"id":1, ...}
# 3. 发消息
curl -sS -X POST $BASE/contacts/SOURCE_ID/conversations/1/messages \
  -H "Content-Type: application/json" -d '{"content":"你好"}'
# 4. 拉取消息
curl -sS $BASE/contacts/SOURCE_ID/conversations/1/messages

用网站浮窗的 data-token 调这些接口会返回 404，请务必使用开放接口渠道的标识。

Webhook 事件与签名

在后台「设置 → 集成 → Webhook」添加你的接收地址。新账号开通时，系统会自动挂上青鸾派内部钩子（阿鸾），你仍可再加自己的业务钩子。

常见事件

  • message_created — 新消息
  • conversation_created — 新会话
  • conversation_status_changed — 会话状态变更
  • webwidget_triggered — 浮窗被打开

验签

若配置了 Webhook 密钥，请求头会带签名。用密钥对原始 body 做 HMAC-SHA256，与头里的签名比对：

import hmac, hashlib
def valid(body: bytes, secret: str, header_sig: str) -> bool:
    dig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(dig, header_sig or "")

请在 5 秒内返回 2xx，耗时逻辑放到异步队列，避免重试风暴。

常见问题

浮窗不显示？

检查 data-token 是否正确、页面是否 https、控制台是否有脚本拦截。Safari 隐私模式需允许第三方 Cookie（浮窗走同域 iframe，一般无此问题）。

注册时收不到验证邮件？

注册需要使用真实可收信的邮箱，验证后才能登录。带「+」的别名地址部分邮箱服务商不支持，请先查看垃圾箱，或改用常规邮箱重新注册。

如何区分多位登录用户？

登录后调用 $qingluan.setUser，并尽量开启 HMAC，避免身份被伪造。

阿鸾不回答？

确认知识库有启用条目、工作室里阿鸾开关为开、会话尚未被人工接管。

开放接口 401？

令牌是否复制完整、是否放在 api_access_token 头（不是 Bearer）、账号是否被停用。

能去掉「青鸾派」品牌吗？

团队版可在浮窗外观里隐藏品牌字样；企业版支持更深定制。