跳到主要内容

在线状态下消息推送前的回调

功能说明​

在消息发送至客户端前，App 业务服务端可以通过该回调接收到发送消息的请求。业务服务端可以根据需要对消息进行拦截、修改或添加额外的推送信息。

注意事项​

  • 为启用回调，必须配置回调 URL，并开启本条回调协议对应的开关。配置方法详见 回调说明 文档。
  • 回调的方向是 OpenIMServer 向 App 后台发起 HTTP/HTTPS POST 请求。
  • App 业务服务端在收到回调请求后，需在超时时间内做出响应。

可能触发该回调的场景​

  • 群成员退出群组。
  • 群成员被踢出群组。
  • 群组解散。

回调发生时机​

  • OpenIMServer 准备向客户端推送消息前。

接口说明​

请求 URL 示例​

以下示例中 App 配置的回调 URL 为 http://www.example.com/callbackCommand?contenttype=json。

http://www.example.com/callbackBeforePushCommand?contenttype=json

请求参数说明​

参数说明
http请求协议为 HTTP，请求方式为 POST
www.example.comconfigy.yaml 中的 callback.url 字段，域名或主机名
CallbackCommand此处为：callbackBeforePushCommand
contenttype固定值为：JSON
header名示例值选填类型说明
operationID1646445464564必填stringoperationID用于全局链路追踪

请求包示例​

{
  "callbackCommand": "callbackBeforePushCommand",
  "platformID": 1,
  "platform": "iOS",
  "userIDList": ["user123", "user456"],
  "title": "New Message",
  "desc": "You have a new message",
  "ex": "Extra push info",
  "iOSPushSound": "default",
  "iOSBadgeCount": true,
  "signalInfo": "Signal data",
  "clientMsgID": "msg123",
  "sendID": "user789",
  "groupID": "group123",
  "contentType": 1,
  "sessionType": 2,
  "atUserIDList": ["user101", "user102"],
  "content": "Hello, this is a test message"
}

请求包字段说明​

字段类型描述
callbackCommandstring回调命令，这里是消息推送前的回调
platformIDint平台ID（如 1 代表 iOS，2 代表 Android）
platformstring平台名称（如 iOS、Android）
userIDListarray用户ID列表，表示哪些用户将接收此消息
titlestring推送消息的标题
descstring推送消息的描述或正文内容
exstring额外的推送信息
iOSPushSoundstringiOS 设备上推送消息时使用的声音
iOSBadgeCountboolean是否在iOS应用图标上显示未读消息数
signalInfostring附加信号数据，用于传递额外信息
clientMsgIDstring客户端消息ID
sendIDstring发送者ID
groupIDstring群组ID（如果消息是发送到群组的）
contentTypeint消息内容类型的ID
sessionTypeint会话类型的ID
atUserIDListarray被@用户的ID列表
contentstring发送的消息内容

应答包示例​

允许推送​

允许消息被推送到客户端。

{
    "actionCode": 0,
    "errCode": 0,
    "errMsg": "Success",
    "errDlt": "",
    "nextCode": "",
    "userIDList": ["user123", "user456"],
    "offlinePushInfo": {
        "title": "New Message",
        "desc": "You have a new message",
        "ex": "Extra push info",
        "iOSPushSound": "default",
        "iOSBadgeCount": true,
        "signalInfo": "Signal data"
    }
}

应答包字段说明​

字段类型描述
actionCode0表示业务系统的回调是否正确执行。0表示操作成功。
errCode5001表示自定义错误码，范围在5000-9999之间。在 actionCode 不等于0时设置；在 nextCode 等于1时设置。
errMsg"An error message"自定义错误码对应的简单错误信息。
errDlt"Detailed error information"自定义错误码对应的详细错误信息。
nextCode1下一步执行指令，1表示拒绝继续执行，actionCode 等于0时设置。
userIDListarray用户ID列表，表示允许接收消息的用户。
offlinePushInfoobject离线推送信息对象。