发送自定义系统通知
更新时间: 2024/07/17 17:57:34
网易云信服务端支持发送自定义系统通知。
功能描述
自定义系统通知区别于普通消息,方便开发者进行业务逻辑的通知。目前支持两种自定义系统通知类型:点对点类型 和 群类型(仅限高级群),通过 msgType 参数进行区分。
典型应用场景:某个用户给另一个用户发送好友请求,开发者可自定义该请求的具体内容(建议是 JSON 格式)。
- 支持收发在线和离线自定义系统通知,且支持接收方多端同步接收自定义系统通知。
- 自定义系统通知不支持漫游且不支持保存为云端历史记录。
API 使用限制
单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
URL
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 的设置如下:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
from | String | 是 | 发送者accid,用户帐号,最大32字符,APP内唯一 |
msgtype | int | 是 | 0:点对点自定义通知,1:群消息自定义通知,其他返回414 |
to | String | 是 | msgtype=0 时需填入接收系统通知的用户的的云信 IM 账号(accid),msgtype=1 时需填入接收系统通知的群的 ID(即 tid),最大 32 字符 |
attach | String | 是 | 自定义系统通知的具体内容,开发者组装的字符串,建议 JSON 格式,最大长度 4096 字符 |
pushcontent | String | 否 | 推送文案,最长 500 个字符。更多推送说明请参见 推送配置参数详解。 |
payload | String | 否 | 推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置 |
sound | String | 否 | 如果有指定推送,此属性指定为客户端本地的声音文件名,长度不要超过 30 个字符,如果不指定,会使用默认声音 |
save | int | 否 | 只能传入 1 或 2,1 表示只发在线,2 表示会存离线,传入其他值将报错(状态码:414)。默认会存离线 |
option | String | 否 | 发消息时特殊指定的行为选项,JSON 格式,可用于指定该自定义系统通知是否计入未读数等特殊行为。option 中字段如果不填,则自动使用默认值 option 示例: {"badge":false,"needPushNick":false,"route":false} 字段说明:
|
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 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
403 | 应用权限校验失败,被禁止访问 | - |
500 | 服务出错 | - |
后续步骤
通过服务端发送自定义系统通知后,您可以在客户端监听自定义系统通知接收回调。 各端参考文档如下:
此文档是否对你有帮助?