自定义渠道 SPI 调用说明

1. 适用范围

该协议版本为 OpenKF HTTP SPI v1，用于新合作方与Chatdoing之间传输客服消息、会话状态和访客信息。

协议中的双方职责如下：

方向	发起方	接收方	用途
出站	chatdoing	合作方平台	发送消息、转人工、查询访客
回调	合作方平台	chatdoing	推送客服事件

所有业务 body 必须使用 AES-256-GCM 加密；HTTPS 仍是必需的传输层保护，不能以应用层加密替代。

2. 启用与应用配置

配置如下，示例中的值不可用于生产

{
  "appid": "partner-app-id",
  "host": "https://partner.example.com",
  "key_id": "open-kf-202608",
  "key": "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
}

字段	要求	说明
`appid`	非空字符串	合作方的平台应用标识，写入 `X-OpenKF-App-ID`
`host`	HTTPS 绝对 URL，无 userinfo	chatdoing 调用合作方的基础地址
`key_id`	非空字符串	当前 active 加密密钥版本
`key`	标准 Base64 编码的 32 字节随机值	当前 active AES-256 密钥

3. 加密信封

3.1 HTTP 约束

所有请求和成功可加密响应均使用：

Content-Type: application/octet-stream
Body: AES-256-GCM ciphertext || tag

body 是原始字节，不能再包装为 JSON、Base64 或表单。明文 JSON 最大为 1 MiB；GCM tag 固定为 16 字节。

当接收方无法安全构造加密响应时，例如缺少完整协议头、非法本地 appID 或未知 key_id，回调接口会以 HTTP 400 返回最小明文 JSON 错误。其他已完成头和密钥校验后的回调响应均为加密 body。

3.2 必填请求头

Header	值与格式
`X-OpenKF-Version`	固定 `1`
`X-OpenKF-Direction`	请求为 `request`，响应或 ACK 为 `response`
`X-OpenKF-App-ID`	合作方 `appid`
`X-OpenKF-Key-ID`	本次使用的密钥版本
`X-OpenKF-Algorithm`	固定 `AES-256-GCM`
`X-OpenKF-Timestamp`	Unix 毫秒时间戳字符串，与接收方时钟差不得超过 5 分钟
`X-OpenKF-Nonce`	标准 Base64 编码的 16 字节随机值，用于防重放
`X-OpenKF-IV`	标准 Base64 编码的 12 字节随机 GCM nonce
`X-OpenKF-Request-ID`	一次逻辑请求的稳定唯一标识，建议 UUID v4

每一次实际 HTTP 传输必须重新生成 timestamp、nonce 和 IV。同一次逻辑调用的自动重试必须保持同一个 request_id。

3.3 AAD 构造

对请求和响应均使用以下固定顺序，以换行符 \n 连接，UTF-8 编码后作为 GCM Additional Authenticated Data：

method\npath\nversion\ndirection\nappID\nkeyID\nalgorithm\ntimestamp\nnonce\niv\nrequestID

其中 method 是大写的 POST，path 仅为 URL path，不包含 scheme、host、query string。例如出站消息接口为：

POST
/open-kf/spi/v1/messages/send
1
request
partner-app-id
open-kf-202608
AES-256-GCM
1700000000000
QUFBQUFBQUFBQUFBQUFBQQ==
AQIDBAUGBwgJCgsM
req-001

双方必须使用完全相同的 method、path 和 header 原始值构造 AAD。任一字段被修改都会使 GCM 认证失败。

4. 合作方实现的出站服务 SPI

chatdoing 作为客户端调用合作方 host 下的三个固定端点。合作方应解密 body、处理业务、以相同 request_id 返回加密的统一响应。

4.1 发送消息

POST {host}/open-kf/spi/v1/messages/send

解密后请求示例：

{
  "msg_id": "msg-20260812-001",
  "chat_id": "chat-001",
  "send_time": 1786492800123,
  "msg_type": 0,
  "content": "您好，请问有什么可以帮您？"
}

支持的 msg_type 如下。消息类型值与本服务内部枚举一致。

`msg_type`	类型	必填业务字段
`0`	文本	`content`
`1`	图片	`file_url`
`2`	语音	`file_url`
`3`	文件	`file_url`
`4`	视频	`file_url`
`7`	位置	`location`
`9`	链接	`link`

位置和链接的字段格式：

{
  "location": {
    "name": "办公园区",
    "address": "广东省广州市...",
    "latitude": 23.1291,
    "longitude": 113.2644
  },
  "link": {
    "title": "帮助中心",
    "desc": "常见问题",
    "url": "https://partner.example.com/help",
    "thumb_url": "https://partner.example.com/help.png"
  }
}

4.2 会话转人工

POST {host}/open-kf/spi/v1/chats/transfer

解密后的 body：

{"chat_id":"chat-001"}

合作方应以 request_id 或自身持久化的会话业务键保证重复调用不会重复转人工。

4.3 查询访客

POST {host}/open-kf/spi/v1/contacts/get

解密后的请求：

{"chat_id":"chat-001","sender_id":"customer-001"}

成功响应的 data 应为：

{
  "sender_id": "customer-001",
  "nickname": "张三",
  "avatar": "https://partner.example.com/avatar.png",
  "gender": 1,
  "unionid": "optional-unionid"
}

无法提供访客查询能力时，必须返回明确的非零业务错误码，不能返回缺少 data 的成功响应。

4.4 统一加密响应

三个端点的响应均为加密 JSON，解密后的结构固定为：

{
  "code": 0,
  "message": "",
  "request_id": "d2b9a0ad-9ac1-4a21-98cc-436be1e37701",
  "duplicate": false,
  "data": null
}

响应 header 的 direction 必须为 response，其余 header 重新生成；响应 app_id、key_id 和 body 中的 request_id 必须与请求对应。成功时 code=0；重复成功可设置 duplicate=true 并返回原结果。

5. 合作方调用本服务的回调 SPI

合作方向 chatdoing 推送事件时，调用为该 Application 配置的回调 URL：

POST /go-im-center/open_customer_service/callback/v1/events/{localAppID}

请求使用第 3 节的加密信封，X-OpenKF-Direction 必须为 request，X-OpenKF-App-ID 必须等于该本地 Application 配置的合作方 appid。

当前仅支持 event_type="event.msg"。解密后 body 示例：

{
  "event_type": "event.msg",
  "msg_id": "partner-msg-001",
  "chat_id": "chat-001",
  "chat_type": 0,
  "chat_status": 1,
  "sender_id": "customer-001",
  "sender_type": 1,
  "send_time": 1786492800123,
  "msg_type": 0,
  "content": "我想咨询产品价格"
}

字段	说明
`chat_type`	`0` 单聊，`1` 群聊
`chat_status`	`1` 人工服务，`2` AI 托管
`sender_type`	`0` 客服/员工，`1` 客户，`2` AI
`msg_type`	取值及载荷字段见 4.1；媒体消息使用 `file_url`，位置使用 `location`，链接使用 `link`

处理成功后，本服务会返回加密 ACK，解密格式同 4.4。相同 msg_id 或 request_id 已成功处理时，ACK 的 code=0 且 duplicate=true，不会再次发布消息事件。

6. 错误、重试与幂等

`code`	含义	是否自动重试
`40001`	信封或 header 非法	否
`40002`	GCM 解密或认证失败	否
`40003`	nonce 重放	否，重新构造新请求才可能重试
`40004`	时间戳超过 5 分钟窗口	否，先校准时钟后重新构造请求
`40005`	协议版本、方向或算法不支持	否
`40006`	事件、动作、发送者或消息类型不支持	否
`40101`	`key_id` 缺失、未知或已 retired	否，更新密钥配置后重新构造请求
`40901`	该请求正在处理，幂等占用冲突	由调用方按退避策略重试
`42900`	业务限流	是
`50000`	服务端内部错误	是

chatdoing 对出站请求的行为为：总共最多 3 次，首次重试等待 100 ms，第二次重试等待 200 ms；单次逻辑调用共享 10 秒超时。HTTP 429 或任意 5xx，以及业务码 42900、50000 都会触发该重试。

合作方实现相同语义时应遵守：

request_id 在一次逻辑操作和其传输重试中保持不变。

每次传输尝试重新生成 16 字节 nonce、12 字节 IV 和当前毫秒时间戳。

在 appid + nonce 维度原子去重，避免重放。

在 appid + request_id 及消息 appid + msg_id 维度保存处理结果，重复请求返回原结果或 duplicate=true，不重复产生业务副作用。

记录日志时只保留 appID、keyID、action、requestID、错误码和耗时；禁止记录 key、明文、完整密文或访问令牌。

7. Go 实现示例

下例展示合作方服务端解密 chatdoing 的请求并构造加密响应所需的核心逻辑。示例只使用 Go 标准库；生产实现还应加入 key 查找、时间窗口校验、nonce 原子占用和持久化幂等记录。

回调发送方复用相同的 crypt、Headers 和 AAD 规则即可。区别仅在于：URL path 为 /go-im-center/open_customer_service/callback/v1/events/{localAppID}，请求 body 为第 5 节的事件 JSON；收到响应后按响应 headers 的 direction=response 解密并检查 request_id、code 与 duplicate。

以下示例基于前述 Headers、Response、crypt、headersFromHTTP 和 validateHeaders，展示合作方调用本服务 POST https://im.example.com/go-im-center/open_customer_service/callback/v1/events/12345 的完整流程。

该函数所在文件需要额外引入：

发生网络超时、HTTP 429/5xx 或 ACK 的业务码为 42900、50000 时，应保持 requestID 不变，重新生成 Timestamp、Nonce、IV，使用新 header 和新密文重发；不可复用同一个 nonce 或 IV。

对接说明

自定义渠道 SPI 调用说明#

1. 适用范围#

2. 启用与应用配置#

3. 加密信封#

3.1 HTTP 约束#

3.2 必填请求头#

3.3 AAD 构造#

4. 合作方实现的出站服务 SPI#

4.1 发送消息#

4.2 会话转人工#

4.3 查询访客#

4.4 统一加密响应#

5. 合作方调用本服务的回调 SPI#

6. 错误、重试与幂等#

7. Go 实现示例#