IM 服务端消息抄送接入指南

功能介绍

游密支持将 IM 消息及用户登录、登出事件抄送至业务服务端。该功能与客户端 SDK 平台无关，各平台共用本接入协议。

消息抄送：业务服务端接收已启用类型的消息，按业务需要处理消息内容及附加属性。
登录、登出事件抄送：业务服务端接收用户登录、登出事件，获取用户 ID、状态及事件时间等信息。

此功能默认不开启，需要的请联系游密开启此服务。

请求方向为：游密服务端 → 业务服务端。业务侧提供接收接口，游密在触发已配置启用的事件时主动发起 HTTP POST 请求。

接入流程

业务侧准备一个可被游密服务访问的 HTTP／HTTPS 接收接口，完整 URL 示例为 https://api.example.com/im/callback/app-a。
联系游密，提供所属应用、接收 URL 及需要接收的事件类型，由游密侧配置启用。仅配置 URL 不代表所有事件都会自动开启。
按本指南分别处理消息回调和登录、登出回调，并实现相应的响应逻辑。
联调已启用的事件，检查接收报文、登录／登出签名计算及 HTTP 响应。

通用请求约定

项目	约定
请求方向	游密服务端 → 业务服务端
请求方法	`POST`
接收地址	业务侧自定义完整 URL，例如 `https://api.example.com/im/callback/app-a`
请求头	`Content-Type: application/json`
请求体	JSON 对象；每次请求包含一条消息或一次登录／登出事件
接收成功	返回 HTTP `2xx`，推荐 `200 OK` 或 `204 No Content`
请求超时	3 秒，包含连接、发送及接收响应的总耗时；业务侧应尽快完成接收并响应
响应体	不要求固定结构，不解析业务状态码；最多 1024 字节，推荐空响应体或简短的 `{"code":0}`

接收 URL 请使用不带查询参数（?…）和片段（#…）的地址，以便兼容登录／登出回调自动追加签名参数的行为。

两类回调使用同一组接收地址，但请求体不同：消息回调包含 from: "youme_msg_cc"、msg_id 等字段；登录／登出回调包含 userId、status、os、time。同一接口应按报文结构区分处理。

请求体没有统一的 app_id／appkey 字段。多个应用共用接收服务时，建议通过不同 URL 路径区分应用。

多地址配置

游密侧支持配置多个接收 URL，使用英文逗号 , 分隔：

TEXT

https://api-a.example.com/im/callback,https://api-b.example.com/im/callback

每个事件会依次向地址列表中的每个地址发送一份回调。一个地址发送失败后，仍会继续尝试后续地址；响应较慢的地址会延后后续地址的发送。同一事件在不同地址上的到达时间不保证一致。

同一组地址会接收该应用所有已启用的抄送事件，当前配置不支持为每个 URL 单独筛选事件。请勿重复配置相同地址，以免重复接收。

消息抄送

请求字段

本表“始终返回”表示当前服务构造回调时一定写入该字段；“条件返回”表示仅在上游消息携带相应数据时写入。业务侧应兼容可选字段缺失、空字符串和新增字段。

字段	JSON 类型	返回条件	说明
`from`	string	始终返回	固定为 `youme_msg_cc`。
`serial_no`	string	始终返回	发送方请求序列号的十进制字符串，用于请求关联、排查问题；不是每次 HTTP 投递单独生成的编号。
`msg_id`	string	始终返回	服务端消息 ID，十进制字符串。应按字符串保存。
`snder_id`	string	始终返回	发送者用户 ID。
`snder_info`	string	条件返回	发送者附加信息，已由游密侧进行 Base64 解码。接收方获得的是原始信息字符串；即使内容是 JSON 文本，外层类型仍为 string。
`recver_id`	string	始终返回	私聊时为接收者用户 ID，频道／房间消息时为频道／房间 ID。多发场景见聊天类型。
`msg_type`	integer	始终返回	消息类型，见消息类型与内容。
`chat_type`	integer	始终返回	聊天类型，见聊天类型。
`msg_content`	string	始终返回	消息内容；不同消息类型的处理方式见消息类型与内容。
`c_time`	string	始终返回	消息创建时间，格式为 `YYYY-MM-DD HH:mm:ss`。
`msg_comment`	object 或 null	条件返回	消息附加属性。非空时为字符串键值对对象；上游携带空备注结构时可能返回 `null`。
`recver_online_status`	integer	始终返回	上游未提供时填 `0`；接收者离线／非活跃，或房间中存在离线／非活跃用户时填 `2`。`0` 不能作为接收者确实在线的证明。
`user_ip`	string	条件返回	上游提供的发送用户 IP 地址，例如 `192.0.2.10`。
`offline_userid`	string	条件返回	接收消息的离线／非活跃用户 ID 列表，使用英文逗号分隔，例如 `user_002,user_003`。类型为 string。

消息类型与内容

`msg_type`	消息类型	`msg_content` 说明
`6`	文本消息	原始消息内容字符串。
`7`	语音消息	原样转发上游内容；按既有语音协议通常为语音资源 URL，不附带音频文件。
`8`	文件消息	原样转发上游内容字符串，具体内容格式由发送端文件消息协议决定；回调不上传文件附件。
`12`	二进制消息	原始消息字节经过 Base64 编码后的字符串，业务侧 Base64 解码后获得原始字节。
`15`	礼物消息	固定字符串 `礼物消息`，不返回原始礼物内容。

msg_comment 中的键名和含义由发送端／SDK 决定，抄送接口不规定固定的业务键。例如部分语音消息可能包含 AudioText，但业务侧不能假定该键始终存在。所有属性值按字符串输出，不按上游的类型标记转换为数字或布尔值。

聊天类型

`chat_type`	含义	接收者说明
`1`	私聊	`recver_id` 为接收用户 ID。
`2`	频道／房间消息	`recver_id` 为频道／房间 ID。
`3`	多发	上游支持的多接收者发送类型。当前抄送直接转发上游 `recv_id`，不会转换成 JSON 用户数组。

多发上游使用序列化的 Protobuf RecverList 表示接收者列表，当前抄送层没有为其做 Base64 编码或结构化转换。如需接入 chat_type=3，需单独联调其接收者字段，不能按私聊用户 ID 或逗号分隔列表解析。

文本消息示例

以下时间示例假设抄送服务使用 UTC+8 时区。示例域名、用户和消息均为演示数据。

HTTP

POST /im/callback/app-a HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "from": "youme_msg_cc",
  "serial_no": "123456",
  "msg_id": "1316476776335015937",
  "snder_id": "user_001",
  "snder_info": "{\"nickname\":\"玩家一\"}",
  "recver_id": "user_002",
  "msg_type": 6,
  "chat_type": 1,
  "msg_content": "你好",
  "c_time": "2026-09-10 12:00:00",
  "msg_comment": {
    "business_tag": "customer_service"
  },
  "recver_online_status": 0,
  "user_ip": "192.0.2.10"
}

二进制消息示例

JSON

{
  "from": "youme_msg_cc",
  "serial_no": "123457",
  "msg_id": "1316476776335015938",
  "snder_id": "user_001",
  "recver_id": "user_002",
  "msg_type": 12,
  "chat_type": 1,
  "msg_content": "SGVsbG8=",
  "c_time": "2026-09-10 12:00:00",
  "recver_online_status": 2
}

示例中的 SGVsbG8= 解码后为字节内容 Hello。

消息回调鉴权

当前消息回调不生成 nonce、timestamp、signature，也不附带 Authorization 请求头。登录与登出事件抄送中的签名规则仅适用于登录／登出回调。业务侧不能对所有回调统一要求这三个签名参数。

登录与登出事件抄送

配置相应事件后，游密会将用户登录／登出状态以 JSON 请求体发送至同一组接收地址，并在 URL 查询参数中附加签名。

URL 查询参数

参数	类型	必须	说明
`nonce`	string	是	游密生成的随机数，以十进制字符串传递。
`timestamp`	string	是	发起本次回调时的 Unix 时间戳，单位为秒。
`signature`	string	是	SHA-1 签名，以 40 位小写十六进制字符串传递。

参数位于 URL 查询串，不在 JSON 请求体或请求头中。接收方应按参数名读取，不依赖参数排列顺序。

JSON 请求体

字段	JSON 类型	必须	说明
`userId`	string	是	用户 ID。
`status`	integer	是	`0`：登录／上线；`2`：登出／下线。
`os`	integer	是	登录请求中的操作系统类型编号；登出时使用会话中保存的编号。按接入 SDK 的 `os_type` 定义解释，当前回调层不转换该值。
`time`	string	是	事件生成时的 Unix 时间戳，单位为毫秒，以十进制字符串传递。

JSON 中的 time 是毫秒，URL 中的 timestamp 是秒，二者也分别在生成事件和发起回调时取值，不要求完全对应。

该回调说明当前登录服务产生的登录／登出事件；不能据此假定心跳超时、网络中断等所有离线原因都会触发同样的通知。

签名算法

TEXT

待签名字符串 = appSecret + nonce + timestamp
signature = SHA1(待签名字符串的字节).小写十六进制表示

当前参与签名计算的 appSecret 为空字符串，计算时使用空字符串。

按上述顺序直接拼接，不添加分隔符，不排序，不拼接参数名。使用字符串形式的 nonce 和 timestamp。

登录请求示例

HTTP

POST /im/callback/app-a?nonce=123456&signature=d38fbeb6688dddb01c5d73d21098fc4fdc2a4c69&timestamp=1789012800 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "userId": "user_001",
  "status": 0,
  "os": 1,
  "time": "1789012800000"
}

登出请求使用同样的字段结构，status 为 2，时间及 URL 签名参数按本次事件生成。

接收与响应

成功接收后，推荐返回：

HTTP

HTTP/1.1 204 No Content

也可以返回：

HTTP

HTTP/1.1 200 OK
Content-Type: application/json

{"code":0}

成功判定要求 HTTP 请求正常完成且状态码为 200～299。响应体中的 code、message 等业务字段不参与判定。

业务处理耗时较长时，建议先完成可靠入库或入队，再及时返回成功，后续异步处理。重复收到且已接收过的事件也应正常返回成功。

响应体不得超过 1024 字节，否则即使返回 2xx 也会因响应读取失败而被记为失败。请直接返回最终状态，不使用 3xx 重定向。

文档目录

IM 服务端消息抄送接入指南

功能介绍

接入流程

通用请求约定

多地址配置

消息抄送

请求字段

消息类型与内容

聊天类型

文本消息示例

二进制消息示例

消息回调鉴权

登录与登出事件抄送

URL 查询参数

JSON 请求体

签名算法

登录请求示例

接收与响应