API 参考
圈组

发送自定义系统通知

更新时间: 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 的设置如下:

参数类型必填说明
fromString发送者accid,用户帐号,最大32字符,APP内唯一
msgtypeint0:点对点自定义通知,1:群消息自定义通知,其他返回414
toStringmsgtype=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 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码

状态码 说明 处理建议
200 请求成功 -
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
403 应用权限校验失败,被禁止访问 -
500 服务出错 -

后续步骤

通过服务端发送自定义系统通知后,您可以在客户端监听自定义系统通知接收回调。 各端参考文档如下:

此文档是否对你有帮助?
有帮助
去反馈
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码
  • 后续步骤