发送自定义系统通知
更新时间: 2024/07/17 17:57:34
网易云信服务端支持发送自定义系统通知。
自定义系统通知区别于普通消息,方便开发者进行业务逻辑的通知。目前支持两种自定义系统通知类型: 点对点类型 和 群类型 (仅限高级群),通过 msgType 参数进行区分。
典型应用场景:某个用户给另一个用户发送好友请求,开发者可自定义该请求的具体内容(建议是 JSON 格式)。
API 使用限制
单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
httpPOST https://api.netease.im/nimserver/msg/sendAttachMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
POST 请求中 Headers 的设置请参考 API 调用方式。
POST 请求中 Body 的设置如下:
参数类型必填说明
fromString是发送者accid,用户帐号,最大32字符,APP内唯一
msgtypeint是0:点对点自定义通知,1:群消息自定义通知,其他返回414
toString是msgtype=0 时需填入接收系统通知的用户的的云信 IM 账号(accid),msgtype=1 时需填入接收系统通知的群的 ID(即 tid),最大 32 字符
attachString是自定义系统通知的具体内容,开发者组装的字符串,建议 JSON 格式,最大长度 4096 字符
pushcontentString否推送文案,最长 500 个字符。更多推送说明请参见 推送配置参数详解。若未设置 pushcontent 字段,则不会触发推送服务,但会将 payload 字段内容下发给客户端。
payloadString否推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置
soundString否如果有指定推送,此属性指定为客户端本地的声音文件名,长度不要超过 30 个字符,如果不指定,会使用默认声音
saveint否只能传入 1 或 2,1 表示只发在线,2 表示会存离线,传入其他值将报错(状态码:414)。默认会存离线
option String否发消息时特殊指定的行为选项,JSON 格式,可用于指定该自定义系统通知是否计入未读数等特殊行为。option 中字段如果不填,则自动使用默认值
option 示例:
{"badge":false,"needPushNick":false,"route":false}
字段说明:
- badge:该系统通知是否需要计入到未读计数中,默认 true
- needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认 false (注意默认值与sendMsg.action 接口的 needPushNick 有别)
- route: 该消息是否需要抄送至您指定的应用服务器;默认true (需要应用开通消息抄送功能)
isForcePush boolean 否 发自定义系统通知时,是否强制推送,默认 false
forcePushContent String 否 发自定义系统通知时,强制推送的文案,最长 500 个字符
forcePushAll boolean 否 发群自定义系统通知时,强推列表是否为群里除发送者外的所有有效成员,默认 false
forcePushList String 否 发群自定义系统通知时的强推列表,格式为 JSONArray,示例:["accid1","accid2"],列表内最多 100 个用户 env String 否系统通知需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称(如下图),最大 32 个字符

checkAccidAsyncEnable boolean 否 是否 异步 检查用户账号 ID。默认为 false。
若设为 true,表示开启异步检查。开启后,无效账号不会再返回 且 返回结果中不会包含 unregister 字段。当发送对象较多,且耗时较长时,建议开启该配置。
cURL请求示例
curlcurl -X POST -H "AppKey: go9dnk49***lw0803mgq3" -H "Nonce: 4tggger**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&msgtype=0&to=lisi&attach={"myattach":"test"}' 'https://api.netease.im/nimserver/msg/sendAttachMsg.action'
请求成功返回示例
json"Content-Type": "application/json; charset=utf-8"
"code":200
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
"code":414
"desc":"check msgType" // msgType参数不是"0"或"1"
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。