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

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

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

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

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

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

{
  "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"
  }
}

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

{"chat_id":"chat-001"}

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

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

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

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

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

{
  "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": "我想咨询产品价格"
}

// openkfspi.mjs — 合作方向 go-im-center 推送 event.msg 回调的示例。
// 使用 Node.js 内置模块，无需 npm install。

import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
import https from 'node:https';

const CONTENT_TYPE  = 'application/octet-stream';
const CALLBACK_URL  = 'https://im.example.com/go-im-center/open_customer_service/callback/v1/events/12345';
const CALLBACK_PATH = '/go-im-center/open_customer_service/callback/v1/events/12345';
const TAG_LENGTH    = 16;

/**
 * 按第 3.3 节固定顺序构造 AAD，以 \n 连接，UTF-8 编码。
 */
function buildAad(method, path, version, direction, appId, keyId,
                  algorithm, timestamp, nonce, iv, requestId) {
  return Buffer.from(
    [method, path, version, direction, appId, keyId, algorithm,
     timestamp, nonce, iv, requestId].join('\n'),
    'utf-8'
  );
}

/**
 * AES-256-GCM 加密，返回 ciphertext || tag 原始 Buffer。
 */
function encrypt(key, iv, aad, plaintext) {
  const cipher = createCipheriv('aes-256-gcm', key, iv);
  cipher.setAAD(aad);
  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
  const tag = cipher.getAuthTag(); // 16 字节
  return Buffer.concat([encrypted, tag]);
}

/**
 * AES-256-GCM 解密，输入为 ciphertext || tag 原始 Buffer。
 */
function decrypt(key, iv, aad, input) {
  if (input.length < TAG_LENGTH) {
    throw new Error('Ciphertext too short');
  }
  const ciphertext = input.subarray(0, input.length - TAG_LENGTH);
  const tag = input.subarray(input.length - TAG_LENGTH);
  const decipher = createDecipheriv('aes-256-gcm', key, iv);
  decipher.setAAD(aad);
  decipher.setAuthTag(tag);
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
}

/**
 * 向 go-im-center 推送一条 event.msg 回调并解密 ACK。
 *
 * @param {Buffer} key    32 字节 AES 密钥
 * @param {string} appId  合作方 appid
 * @param {string} keyId  当前密钥版本
 * @returns {Promise<object>} 解密后的 ACK
 */
function pushEvent(key, appId, keyId) {
  return new Promise((resolve, reject) => {
    // 生成 16 字节 nonce、12 字节 IV，Base64 编码
    const nonceB64  = randomBytes(16).toString('base64');
    const ivB64     = randomBytes(12).toString('base64');
    const requestId = randomBytes(16).toString('hex');
    const timestamp = String(Date.now());

    const version   = '1';
    const direction = 'request';
    const algorithm = 'AES-256-GCM';

    // 构造 AAD
    const aad = buildAad('POST', CALLBACK_PATH, version, direction,
                          appId, keyId, algorithm, timestamp,
                          nonceB64, ivB64, requestId);

    // 构造 event.msg body
    const event = {
      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:   Date.now(),
      msg_type:    0,
      content:     '我想咨询产品价格',
    };
    const plaintext  = Buffer.from(JSON.stringify(event), 'utf-8');
    const ivBytes    = Buffer.from(ivB64, 'base64');
    const ciphertext = encrypt(key, ivBytes, aad, plaintext);

    const headers = {
      'Content-Type':        CONTENT_TYPE,
      'X-OpenKF-Version':    version,
      'X-OpenKF-Direction':  direction,
      'X-OpenKF-App-ID':     appId,
      'X-OpenKF-Key-ID':     keyId,
      'X-OpenKF-Algorithm':  algorithm,
      'X-OpenKF-Timestamp':  timestamp,
      'X-OpenKF-Nonce':      nonceB64,
      'X-OpenKF-IV':         ivB64,
      'X-OpenKF-Request-ID': requestId,
    };

    const url = new URL(CALLBACK_URL);
    const options = {
      hostname: url.hostname,
      port:     url.port || 443,
      path:     url.pathname,
      method:   'POST',
      headers,
    };

    const req = https.request(options, (res) => {
      const chunks = [];
      res.on('data', (chunk) => chunks.push(chunk));
      res.on('end', () => {
        try {
          if (res.statusCode < 200 || res.statusCode >= 300) {
            // 非 2xx 可能是明文错误 JSON
            return reject(new Error(`Callback HTTP status: ${res.statusCode}`));
          }
          const respContentType = res.headers['content-type'] || '';
          if (respContentType !== CONTENT_TYPE) {
            return reject(new Error(`Unexpected response Content-Type: ${respContentType}`));
          }

          const respDirection = res.headers['x-openkf-direction'] || '';
          const respRequestId = res.headers['x-openkf-request-id'] || '';
          if (respDirection !== 'response') {
            return reject(new Error(`Unexpected response direction: ${respDirection}`));
          }
          if (respRequestId !== requestId) {
            return reject(new Error('Response request_id mismatch'));
          }

          // 用响应的全部 header 构造 AAD 并解密 ACK
          const respIvB64 = res.headers['x-openkf-iv'] || '';
          const respIv    = Buffer.from(respIvB64, 'base64');
          const respAad   = buildAad('POST', CALLBACK_PATH,
            res.headers['x-openkf-version'] || '',
            respDirection,
            res.headers['x-openkf-app-id'] || '',
            res.headers['x-openkf-key-id'] || '',
            res.headers['x-openkf-algorithm'] || '',
            res.headers['x-openkf-timestamp'] || '',
            res.headers['x-openkf-nonce'] || '',
            respIvB64, respRequestId);

          const respBody      = Buffer.concat(chunks);
          const ackPlaintext  = decrypt(key, respIv, respAad, respBody);
          const ack           = JSON.parse(ackPlaintext.toString('utf-8'));
          resolve(ack);
        } catch (err) {
          reject(err);
        }
      });
    });

    req.on('error', reject);
    req.write(ciphertext); // 原始二进制 body
    req.end();
  });
}

// 使用示例
const key = Buffer.from('MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=', 'base64');
pushEvent(key, 'partner-app-id', 'open-kf-202608')
  .then((ack) => console.log('ACK:', JSON.stringify(ack, null, 2)))
  .catch((err) => console.error('Error:', err));

// OpenKFCallbackExample.cs — 合作方向 go-im-center 推送 event.msg 回调的示例。
// 依赖 .NET 6+，无需 NuGet 额外包。

using System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

namespace OpenKF.SPI;

public static class OpenKFCallbackExample
{
    private const string ContentType       = "application/octet-stream";
    private const string CallbackUrl       = "https://im.example.com/go-im-center/open_customer_service/callback/v1/events/12345";
    private const string CallbackPath      = "/go-im-center/open_customer_service/callback/v1/events/12345";
    private const int    TagLength         = 16;
    private const int    NonceLength       = 16; // header nonce
    private const int    GcmIvLength       = 12; // GCM IV

    // ========== AAD 与加密工具 ==========

    /// <summary>
    /// 按第 3.3 节固定顺序构造 AAD，以 \n 连接，UTF-8 编码。
    /// </summary>
    private static byte[] BuildAad(
        string method, string path, string version, string direction,
        string appId, string keyId, string algorithm,
        string timestamp, string nonce, string iv, string requestId)
    {
        string joined = string.Join("\n",
            method, path, version, direction,
            appId, keyId, algorithm,
            timestamp, nonce, iv, requestId);
        return Encoding.UTF8.GetBytes(joined);
    }

    /// <summary>
    /// AES-256-GCM 加密，返回 ciphertext || tag 原始字节。
    /// </summary>
    private static byte[] Encrypt(byte[] key, byte[] nonce, byte[] aad, byte[] plaintext)
    {
        // AesGcm.Encrypt 输出 ciphertext，tag 由 tag 参数填充
        byte[] ciphertext = new byte[plaintext.Length];
        byte[] tag = new byte[TagLength];
        using var aes = new AesGcm(key);
        aes.Encrypt(nonce, plaintext, ciphertext, tag, aad);
        // 拼接 ciphertext || tag
        return ciphertext.Concat(tag).ToArray();
    }

    /// <summary>
    /// AES-256-GCM 解密，输入为 ciphertext || tag 原始字节。
    /// </summary>
    private static byte[] Decrypt(byte[] key, byte[] nonce, byte[] aad, byte[] data)
    {
        if (data.Length < TagLength)
            throw new ArgumentException("Ciphertext too short");

        byte[] ciphertext = data[..^TagLength];
        byte[] tag        = data[^TagLength..];
        byte[] plaintext  = new byte[ciphertext.Length];
        using var aes = new AesGcm(key);
        aes.Decrypt(nonce, ciphertext, tag, plaintext, aad);
        return plaintext;
    }

    // ========== 回调发送示例 ==========

    /// <summary>
    /// 向 go-im-center 推送一条 event.msg 回调并解密 ACK。
    /// </summary>
    public static async Task<string> PushEventAsync(
        byte[] key, string appId, string keyId, HttpClient client)
    {
        // 生成 16 字节 nonce、12 字节 IV，Base64 编码
        byte[] nonceBytes = RandomNumberGenerator.GetBytes(NonceLength);
        byte[] ivBytes    = RandomNumberGenerator.GetBytes(GcmIvLength);
        string nonceB64   = Convert.ToBase64String(nonceBytes);
        string ivB64      = Convert.ToBase64String(ivBytes);
        string requestId  = Guid.NewGuid().ToString();
        string timestamp  = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString();

        string version   = "1";
        string direction = "request";
        string algorithm = "AES-256-GCM";

        // 构造 AAD
        byte[] aad = BuildAad("POST", CallbackPath, version, direction,
            appId, keyId, algorithm, timestamp, nonceB64, ivB64, requestId);

        // 构造 event.msg body
        var evt = new
        {
            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   = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
            msg_type    = 0,
            content     = "我想咨询产品价格",
        };
        byte[] plaintext  = Encoding.UTF8.GetBytes(JsonSerializer.Serialize(evt));
        byte[] ciphertext = Encrypt(key, ivBytes, aad, plaintext);

        // 构造 HTTP 请求，body 为原始二进制
        var request = new HttpRequestMessage(HttpMethod.Post, CallbackUrl)
        {
            Content = new ByteArrayContent(ciphertext)
        };
        request.Content.Headers.ContentType =
            new System.Net.Http.Headers.MediaTypeHeaderValue(ContentType);
        request.Headers.Add("X-OpenKF-Version",    version);
        request.Headers.Add("X-OpenKF-Direction",  direction);
        request.Headers.Add("X-OpenKF-App-ID",     appId);
        request.Headers.Add("X-OpenKF-Key-ID",     keyId);
        request.Headers.Add("X-OpenKF-Algorithm",  algorithm);
        request.Headers.Add("X-OpenKF-Timestamp",  timestamp);
        request.Headers.Add("X-OpenKF-Nonce",      nonceB64);
        request.Headers.Add("X-OpenKF-IV",         ivB64);
        request.Headers.Add("X-OpenKF-Request-ID", requestId);

        HttpResponseMessage resp = await client.SendAsync(request);
        if (resp.StatusCode < HttpStatusCode.OK ||
            resp.StatusCode >= HttpStatusCode.MultipleChoices)
        {
            // 非 2xx 可能是明文错误 JSON，按 code 处理
            throw new InvalidOperationException(
                $"Callback HTTP status: {(int)resp.StatusCode}");
        }

        string? respContentType = resp.Content.Headers.ContentType?.MediaType;
        if (respContentType != ContentType)
        {
            throw new InvalidOperationException(
                $"Unexpected response Content-Type: {respContentType}");
        }

        // 校验响应 header
        string? respDirection  = resp.Headers.TryGetValues("X-OpenKF-Direction", out var d)
                                 ? d.FirstOrDefault() : null;
        string? respRequestId  = resp.Headers.TryGetValues("X-OpenKF-Request-ID", out var r)
                                 ? r.FirstOrDefault() : null;
        if (respDirection != "response")
            throw new InvalidOperationException($"Unexpected response direction: {respDirection}");
        if (respRequestId != requestId)
            throw new InvalidOperationException("Response request_id mismatch");

        // 用响应的全部 header 构造 AAD 并解密 ACK
        string? respIvB64 = resp.Headers.TryGetValues("X-OpenKF-IV", out var vi)
                            ? vi.FirstOrDefault() : null;
        byte[] respIv     = Convert.FromBase64String(respIvB64 ?? "");
        byte[] respAad    = BuildAad("POST", CallbackPath,
            resp.Headers.TryGetValues("X-OpenKF-Version", out var rv)
                ? rv.FirstOrDefault() ?? "" : "",
            respDirection ?? "",
            resp.Headers.TryGetValues("X-OpenKF-App-ID", out var ra)
                ? ra.FirstOrDefault() ?? "" : "",
            resp.Headers.TryGetValues("X-OpenKF-Key-ID", out var rk)
                ? rk.FirstOrDefault() ?? "" : "",
            resp.Headers.TryGetValues("X-OpenKF-Algorithm", out var rl)
                ? rl.FirstOrDefault() ?? "" : "",
            resp.Headers.TryGetValues("X-OpenKF-Timestamp", out var rt)
                ? rt.FirstOrDefault() ?? "" : "",
            resp.Headers.TryGetValues("X-OpenKF-Nonce", out var rn)
                ? rn.FirstOrDefault() ?? "" : "",
            respIvB64 ?? "", respRequestId ?? "");

        byte[] respBody      = await resp.Content.ReadAsByteArrayAsync();
        byte[] ackPlaintext  = Decrypt(key, respIv, respAad, respBody);
        return Encoding.UTF8.GetString(ackPlaintext);
    }

    public static async Task Main(string[] args)
    {
        byte[] key = Convert.FromBase64String(
            "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=");
        using var client = new HttpClient();
        string ackJson = await PushEventAsync(key, "partner-app-id", "open-kf-202608", client);
        Console.WriteLine($"ACK: {ackJson}");
    }
}