CommIM 第三方接入文档

POST http://{gate_host}:11260/rpc/{service}/{method}
Content-Type: application/json
token: {user_token}
x-pcd: {base64_encoded_pbcommdata}
x-app-secret: {app_secret}

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

message PBMessage {
  uint32 version = 1;
  uint32 checkCode = 2;
  uint32 errCode = 3;
  string service = 4;       // 目标服务名
  string hashKey = 5;       // 路由键（通常为用户 IM ID）
  PBCommData pbCommData = 6;
  map<string, string> opts = 7;
  string pbName = 8;        // 具体消息的 protobuf 消息名
  bytes pbData = 9;         // 具体消息的 protobuf 编码数据
  string errDesc = 10;
}

POST http://{gate_host}:11260/rpc/pb_grpc_commim_uaa.UAA/FetchEndPoint
Content-Type: application/json
x-pcd: {base64_pcd}

POST /rpc/pb_grpc_commim_uaa.UAA/Login
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "mypassword123"
}

GET http://{allocator_host}:11000/Allocater/GetWsGate?userId={imId}

const ws = new WebSocket('ws://xxx.xxx.xxx.xxx:11030/ws');
ws.binaryType = 'arraybuffer';

ws.onopen = () => {
  sendLoginReq(ws, imToken, imId, appId);
};

ws.onmessage = (event) => {
  const head = PBMessage.decode(new Uint8Array(event.data));
  handleMessage(head);
};

POST /rpc/pb_grpc_commim_uaa.UAA/Signup
Content-Type: application/json

{
  "username": "zhangsan",
  "phone": "13800138000",
  "password": "mypassword123",
  "code": 456789,
  "nickname": "张三"
}

{
  "code": 0,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "imToken": "im_token_xxxxxxxx",
    "info": {
      "userId": "10086",
      "username": "zhangsan",
      "imId": 10086,
      "phone": "13800138000",
      "nickname": "张三",
      "avatar": "https://default.example.com/avatar_m.png",
      "gender": 1
    }
  }
}

POST /rpc/pb_grpc_commim_uaa.UAA/UserInfo
Content-Type: application/json
token: {user_token}

{}

POST /rpc/pb_grpc_commim_uaa.UAA/UpdateUserInfo

{
  "userId": "10086",
  "info": {
    "nickname": "新昵称",
    "sign": "这是我的新签名"
  },
  "keys": ["nickname", "sign"]
}

GET http://{inter_api_host}:11190/GetIMID?appId={appId}&secret={secret}&userId={userId}

{
  "result": 0,
  "msg": "成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "userIds": {
      "appId": 10001,
      "appUserId": "user_238",
      "imUserId": 50001,
      "lastLoginTime": "2026-05-24T10:00:00Z"
    }
  }
}

PUT http://{inter_api_host}:11190/userInfo/{imId}
Content-Type: application/json

{
  "nickname": "张三",
  "avatar": "https://your-cdn.com/avatar/238.jpg",
  "sign": "这是我的签名"
}

async function integrateCommIM(appId, secret, userId) {
  const imidResp = await fetch(
    `http://inter-api-host:11190/GetIMID?appId=${appId}&secret=${secret}&userId=${userId}`
  );
  const imidData = await imidResp.json();
  const { token, userIds } = imidData.data;
  const imId = userIds.imUserId;

  const wsResp = await fetch(
    `http://allocator-host:11000/Allocater/GetWsGate?userId=${imId}`
  );
  const wsData = await wsResp.json();
  const wsUrl = wsData.data;

  const ws = new WebSocket(wsUrl);
  ws.binaryType = 'arraybuffer';

  ws.onopen = () => {
    sendLoginReq(ws, token, imId, appId);
  };

  ws.onmessage = (event) => {
    handleMessage(new Uint8Array(event.data));
  };
}

function makeXPcd(appId, appUserId, imId, aimId, srcClientType = 2) {
  const pcd = {
    srcId: imId || 0,
    aimId: aimId || 0,
    srcClientType,
    appId,
    appUserId: appUserId || '',
    time: Math.floor(Date.now() / 1000),
  };
  return btoa(JSON.stringify(pcd));
}

// pbName: pb_msg_gate.LoginReq
{
  token: imToken,
  token_type: 2,                     // UNI_USER = 2（推荐）
  clientInfo: {
    modelType: 0,
    packageName: 'com.yourapp.name',
    systemVersion: '1.0.0',
    phoneModels: 'Web',
    appVersion: '1.0.0',
    systemName: 'Browser',
    identifier: 'web-xxxxxx',
    xChannel: 'web'
  },
  deviceToken: '',
  forceLogin: true,                  // 首次登录填 true，静默重连填 false
  version: 1
}

// pbName: pb_msg_gate.LoginRsp
{
  result: 0,                         // 0=成功，非0=失败
  reconnectToken: 'xxxx',            // 重连 token
  msg_sn: 12345,
  app_id: 10001,
  app_user_id: '10086',
  deviceToken: 'device_xxx'
}

// pbName: pb_pub.HeartBeat
// 发送: { type: 0, state: 0 }    PING
// 回复: { type: 0, state: 1 }    PANG

// pbName: pb_msg_gate.KickOffUser
{
  optUId: 10001,
  aimUId: 10086,
  reason: 21,
  desc: '账号在其他设备登录'
}

// PBMessage 封装:
{
  service: '',
  hashKey: String(targetImId),
  pbName: 'pb_msg_gate.ChatText',
  pbCommData: {
    srcId: myImId,
    aimId: targetImId,
    appId: appId,
    appUserId: String(myImId),
    time: 0,
    srcClientType: 2,
    needReadReceipt: true
  }
}

// ChatText 内容:
{
  aim_user_id: targetImId,
  chat_type: 0,
  data: '',
  text: '你好，这是一条测试消息',
  exp: {}
}

// PBMessage 封装:
{
  service: 'group',
  hashKey: String(groupId),
  pbName: 'pb_msg_group.GroupChat',
  pbCommData: {
    srcId: myImId,
    groupId: groupId,
    appId: appId,
    time: 0,
    srcClientType: 2,
    atList: [10002, 10003]
  }
}

// GroupChat 内容:
{
  aim_user_id: 0,
  chat_type: 0,
  data: '',
  text: '大家好！',
  exp: {}
}

const head = PBMessage.decode(new Uint8Array(event.data));
const pbName = head.pbName;

if (pbName === 'pb_msg_gate.ChatText') {
  const ChatText = pbRoot.lookupType('pb_msg_gate.ChatText');
  const msg = ChatText.decode(head.pbData);
  const pcd = head.pbCommData;

  console.log('收到消息:', {
    from: pcd.srcId,
    text: msg.text,
    chatType: msg.chat_type,
    data: msg.data,
    time: pcd.time,
    msgSn: pcd.msgSn
  });
}

// pbName: 'pb_pub.MsgReceipt'
{
  isAtMe: false,
  state: 4,                        // MSG_STATE_READ = 4
  time: 0
}
// pbCommData.aimId = 消息发送者 IM ID
// pbCommData.msgSn = 原消息的 msgSn

// pbName: 'pb_msg_offlineMsg.ReadOfflineMsgRsp'
{
  msgNum: 5,
  msgList: [
    {
      srcUserid: 10002,
      aimUserid: 10086,
      chatType: 0,
      text: '你好',
      data: '',
      sn: 12345,
      time: 1700000000
    }
  ]
}

// service: 'friend', hashKey: String(targetImId)
// pbName: 'pb_msg_friend.ApplyReq'
{
  msg: '你好，我是张三'
}
// pbCommData.aimId = 目标用户 IM ID

// pbName: 'pb_msg_friend.ApplyAnswerReq'
{
  agree: true                  // true=同意, false=拒绝
}

// service: 'group', hashKey: String(myImId)
// pbName: 'pb_msg_group.CreateGroupReq'
{
  name: '项目讨论组',
  memberIds: [10086, 10087, 10088],
  memberCountLimit: 200,
  groupType: 0                  // 0=普通群, 1=聊天室, 2=频道, 3=系统通知
}

GET http://{oss_host}:11070/uploadToken
Authorization: {token}
UserID: {imId}

GET http://{oss_host}:11070/getStsToken?bucketName=commim
Authorization: {token}
UserID: {imId}

{
  "aim_user_id": 10002,
  "chat_type": 1,
  "data": "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/commim/image_123.jpg",
  "text": "",
  "exp": {"width": "800", "height": "600"}
}

interface CallSignal {
  type: CallSignalType       // 信令类型，见上表
  callId: string             // 通话唯一标识，格式: call_{timestamp}_{random6}
  mediaType: CallMediaType   // 'audio' | 'video'
  sdp?: string               // SDP 内容（仅 sdp_offer/sdp_answer 携带）
  candidate?: RTCIceCandidateInit  // ICE 候选（仅 ice_candidate 携带）
  timestamp: number          // 毫秒时间戳
}

data 字段 = "commim_call:" + JSON.stringify(CallSignal)

// 示例：发起视频通话邀请
data = 'commim_call:{"type":"call_invite","callId":"call_1719500000_a3f2k1","mediaType":"video","timestamp":1719500000000}'

// 发送时 chat_type = 7 (CUSTOMIZE)
// exp 扩展字段: { "_callSignal": "1", "callType": "video", "callId": "call_1719500000_a3f2k1" }

function isCallSignal(data) {
  return data && data.startsWith('commim_call:');
}

function decodeCallSignal(data) {
  if (!isCallSignal(data)) return null;
  try {
    return JSON.parse(data.slice('commim_call:'.length));
  } catch {
    return null;
  }
}

// 1. 获取 TURN 凭证
const credResp = await fetch('/api/Turn/GetCredentials', {
  method: 'GET',
  headers: {
    'Authorization': userToken,
    'UserID': String(imId),
  },
});
const credData = await credResp.json();

// 2. 创建 PeerConnection
const pc = new RTCPeerConnection({
  iceServers: [{
    urls: credData.data.urls,
    username: credData.data.username,
    credential: credData.data.credential,
  }],
});

// 3. 获取本地媒体流
const localStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: mediaType === 'video',  // 'audio' | 'video'
});
localStream.getTracks().forEach(track => pc.addTrack(track, localStream));

// 远端媒体流
pc.ontrack = (event) => {
  if (event.streams && event.streams[0]) {
    remoteVideoElement.srcObject = event.streams[0];
  }
};

// ICE 候选 → 通过信令发送给对方
pc.onicecandidate = (event) => {
  if (event.candidate) {
    sendSignal(peerImId, {
      type: 'call_ice_candidate',
      callId: currentCallId,
      mediaType: 'video',
      candidate: event.candidate.toJSON(),
      timestamp: Date.now(),
    });
  }
};

// 连接状态
pc.oniceconnectionstatechange = () => {
  switch (pc.iceConnectionState) {
    case 'connected':
    case 'completed':
      // 通话已建立
      break;
    case 'disconnected':
      // 连接断开，结束通话
      break;
    case 'failed':
      // ICE 连接失败
      break;
  }
};

// 收到 call_answer 后执行
const offer = await pc.createOffer({
  offerToReceiveAudio: true,
  offerToReceiveVideo: true,
});
await pc.setLocalDescription(offer);

// 通过信令发送 SDP Offer
sendSignal(peerImId, {
  type: 'call_sdp_offer',
  callId: currentCallId,
  mediaType: 'video',
  sdp: offer.sdp,
  timestamp: Date.now(),
});

// 收到 call_sdp_offer 后执行
await pc.setRemoteDescription(new RTCSessionDescription({
  type: 'offer',
  sdp: signal.sdp,
}));

const answer = await pc.createAnswer();
await pc.setLocalDescription(answer);

// 通过信令发送 SDP Answer
sendSignal(peerImId, {
  type: 'call_sdp_answer',
  callId: currentCallId,
  mediaType: 'video',
  sdp: answer.sdp,
  timestamp: Date.now(),
});

// 静音/取消静音
function toggleAudio(enabled) {
  localStream.getAudioTracks().forEach(track => {
    track.enabled = enabled;
  });
}

// 开关摄像头
function toggleVideo(enabled) {
  localStream.getVideoTracks().forEach(track => {
    track.enabled = enabled;
  });
}

// 挂断
function hangup() {
  sendSignal(peerImId, {
    type: 'call_hangup',
    callId: currentCallId,
    mediaType: 'video',
    timestamp: Date.now(),
  });
  // 释放资源
  localStream.getTracks().forEach(track => track.stop());
  pc.close();
}

{
  "aim_user_id": 10002,
  "chat_type": 6,
  "text": "",
  "data": "{\"callType\":\"video\",\"duration\":332,\"result\":\"completed\"}"
}

class CommIMCall {
  constructor(imSdk, gateUrl) {
    this.imSdk = imSdk;
    this.gateUrl = gateUrl;
    this.pc = null;
    this.localStream = null;
    this.callId = null;
    this.peerImId = null;
    this.mediaType = 'audio';
    this.iceConfig = null;
    this.iceConfigExpiry = 0;
  }

  // 获取 TURN 凭证（带缓存）
  async getIceConfig() {
    const now = Date.now();
    if (this.iceConfig && now < this.iceConfigExpiry) return this.iceConfig;

    const token = localStorage.getItem('im_token') || '';
    const userId = localStorage.getItem('im_user_id') || '';
    const resp = await fetch(`${this.gateUrl}/Turn/GetCredentials`, {
      headers: { 'Authorization': token, 'UserID': userId },
    });
    const json = await resp.json();
    if (json.result !== 0) throw new Error('TURN 凭证获取失败');

    this.iceConfig = {
      iceServers: [{
        urls: json.data.urls,
        username: json.data.username,
        credential: json.data.credential,
      }],
    };
    this.iceConfigExpiry = now + (json.data.ttl - 300) * 1000;
    return this.iceConfig;
  }

  // 发送信令
  sendSignal(signal) {
    const data = 'commim_call:' + JSON.stringify(signal);
    this.imSdk.sendChatText(this.peerImId, '', 7, data, {
      _callSignal: '1',
      callType: signal.mediaType,
      callId: signal.callId,
    });
  }

  // 发起通话
  async startCall(peerImId, mediaType) {
    this.peerImId = peerImId;
    this.mediaType = mediaType;
    this.callId = `call_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;

    // 获取 TURN 凭证
    const iceConfig = await this.getIceConfig();

    // 获取媒体流
    this.localStream = await navigator.mediaDevices.getUserMedia({
      audio: true,
      video: mediaType === 'video',
    });

    // 创建 PeerConnection
    this.pc = new RTCPeerConnection(iceConfig);
    this.localStream.getTracks().forEach(t => this.pc.addTrack(t, this.localStream));

    // 监听事件
    this.pc.ontrack = (e) => {
      if (e.streams[0]) this.onRemoteStream?.(e.streams[0]);
    };
    this.pc.onicecandidate = (e) => {
      if (e.candidate) {
        this.sendSignal({
          type: 'call_ice_candidate',
          callId: this.callId,
          mediaType: this.mediaType,
          candidate: e.candidate.toJSON(),
          timestamp: Date.now(),
        });
      }
    };

    // 发送邀请
    this.sendSignal({
      type: 'call_invite',
      callId: this.callId,
      mediaType: this.mediaType,
      timestamp: Date.now(),
    });
  }

  // 处理来电信令（在 IM 消息回调中调用）
  async handleSignal(signal, fromImId) {
    if (signal.type === 'call_answer') {
      // 对方接听，创建 Offer
      const offer = await this.pc.createOffer({
        offerToReceiveAudio: true,
        offerToReceiveVideo: true,
      });
      await this.pc.setLocalDescription(offer);
      this.sendSignal({
        type: 'call_sdp_offer', callId: this.callId,
        mediaType: this.mediaType, sdp: offer.sdp, timestamp: Date.now(),
      });
    } else if (signal.type === 'call_sdp_offer') {
      await this.pc.setRemoteDescription(new RTCSessionDescription({
        type: 'offer', sdp: signal.sdp,
      }));
      const answer = await this.pc.createAnswer();
      await this.pc.setLocalDescription(answer);
      this.sendSignal({
        type: 'call_sdp_answer', callId: this.callId,
        mediaType: this.mediaType, sdp: answer.sdp, timestamp: Date.now(),
      });
    } else if (signal.type === 'call_sdp_answer') {
      await this.pc.setRemoteDescription(new RTCSessionDescription({
        type: 'answer', sdp: signal.sdp,
      }));
    } else if (signal.type === 'call_ice_candidate') {
      await this.pc.addIceCandidate(new RTCIceCandidate(signal.candidate));
    } else if (signal.type === 'call_hangup') {
      this.endCall();
    }
  }

  // 挂断
  hangup() {
    this.sendSignal({
      type: 'call_hangup', callId: this.callId,
      mediaType: this.mediaType, timestamp: Date.now(),
    });
    this.endCall();
  }

  // 结束通话（内部）
  endCall() {
    this.localStream?.getTracks().forEach(t => t.stop());
    this.pc?.close();
    this.pc = null;
    this.localStream = null;
    this.callId = null;
  }
}