JIIL Chat 开放平台文档

概述

JIIL Chat 开放平台为开发者提供与 JIIL Chat 生态集成的能力。目前开放 OAuth 授权登录 功能，允许第三方应用获取用户的基本信息（用户名、头像）。

应用类型

平台支持三种类型的应用：

创建应用

登录开发者平台后，点击「创建应用」按钮，填写以下信息即可创建。

参数说明

授权流程

OAuth 授权登录流程如下：

1. 创建应用：在开发者平台创建应用并等待审核通过
2. 发起授权：调用 /oauth/init 创建授权会话，引导用户在 JIIL Chat 客户端确认
3. 轮询结果：调用 /oauth/poll 获取授权结果
4. 获取信息：授权成功后，从轮询响应中取得 username、shadow_user_id 和 sid
5. 展示头像：使用 sid 调用头像接口获取用户头像

1. 创建授权会话

/oauth/init 必须使用 POST 请求，并携带 developer_token 和 app_id。

POST https://chatdev.jiil.top/oauth/init
Content-Type: application/json

{
  "app_id": YOUR_APP_ID,
  "developer_token": "你的开发者令牌"
}

成功响应：

{
  "code": 200,
  "session_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

错误响应：

2. 唤起 JIIL Chat 客户端

通过自定义协议 jiilchat://oauth?session_id=SESSION_ID 唤起用户本机的 JIIL Chat 客户端进行授权确认。

3. 轮询授权结果

GET https://chatdev.jiil.top/oauth/poll?session_id=SESSION_ID

响应状态：

confirmed 响应示例：

{
  "code": 200,
  "status": "confirmed",
  "username": "用户名",
  "shadow_user_id": "s_xxxxxxxxxxxx",
  "sid": "加密头像凭证"
}

字段说明：

头像获取 API

平台提供两个头像获取接口：/logo 通过用户 ID 直接获取头像图片，/kflogo 通过 OAuth 授权得到的 sid 获取头像 JSON 数据。

1. 通过用户 ID 获取头像 /logo

直接返回 webp 图片二进制，适合放在 <img src> 中使用。

GET https://chatava.jiil.top/logo?id=用户ID

参数：

响应：

• 成功：返回 image/webp 二进制数据
• 响应头：X-Avatar-Gender: unknown（或 male / female）
• 失败：返回 JSON 错误（400 / 404 / 429 / 503）

HTML 示例：

<img src="https://chatava.jiil.top/logo?id=123" alt="用户头像">

错误码：

2. 通过 sid 获取头像 /kflogo

使用 OAuth 授权得到的 sid 获取头像，返回 JSON 格式，包含 base64 头像数据、头像标识和性别。

GET https://chatava.jiil.top/kflogo?sid=SID

参数：

响应：

{
  "code": 200,
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "avatar_id": "用户头像标识",
    "avatar": "base64编码的webp头像",
    "gender": "unknown"
  }
}

字段说明：

JavaScript 示例：

const sid = "从 OAuth 轮询获取的 sid";
const res = await fetch('https://chatava.jiil.top/kflogo?sid=' + sid);
const result = await res.json();

if (result.code === 200) {
  const { avatar_id, avatar, gender } = result.data;
  // 拼接 base64 显示头像
  const imgSrc = 'data:image/webp;base64,' + avatar;
}

错误码：

演示应用

// 1. 创建授权会话
const resp = await fetch('https://chatdev.jiil.top/oauth/init', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ app_id: APP_ID, developer_token: TOKEN }),
});
const { session_id } = await resp.json();

// 2. 唤起 JIIL Chat 客户端
window.location.href = 'jiilchat://oauth?session_id=' + session_id;

// 3. 轮询授权结果
const pollResp = await fetch('https://chatdev.jiil.top/oauth/poll?session_id=' + session_id);
const pollData = await pollResp.json();
// pollData: { username, shadow_user_id, sid }

// 4. 调用 /kflogo 获取头像
const avResp = await fetch('https://chatava.jiil.top/kflogo?sid=' + pollData.sid);
const avData = await avResp.json();
// avData.data: { avatar_id, avatar(base64), gender }