API 参考
圈组

发送广播消息

更新时间: 2024/07/17 17:57:35

可以对应用内的所有用户发送广播消息。该功能适用于需要通知所有用户的业务场景,如企业管理层通过内部即时通讯软件向全体员工发送内部通知。

如有需求,也可删除广播消息。

IM 服务端 API 还支持查询历史广播消息,具体请参见广播消息查询

发送广播消息

功能描述

要实现广播消息在客户端的正常接收,需要在客户端注册相应的监听/回调函数,否则将无法接收。具体说明请参见各端 SDK 文档。以 Android 端为例,可参见广播消息收发

  • 目前只支持通过服务端 API 发送广播消息,客户端只能接收广播消息,且只有 4.3.0 及以上版本的 IM SDK 才支持接收。
  • 客户端未登录 IM 的用户(例如通过独立模式进入聊天室的用户)接收不到广播消息。
  • 广播消息目前暂不支持第三方推送(APNS、小米、华为等)、不支持漫游、不支持生成会话。

API 使用限制

  • 广播消息功能需要单独开通,进行相关开发前,请确保您已在云信控制台开通。
  • 单个应用最高调用频率:10 次/分,超限将报错(状态码:416),且应用将被屏蔽 1 分钟,之后才能再次调用。

URL

httpPOST https://api.netease.im/nimserver/msg/broadcastMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

  • POST 请求中 Headers 的设置请参考API调用方式

  • POST 请求中 Body 的设置如下:

参数类型必填说明
body String 广播消息内容,最大 4096 字符
from String 发送者的云信 IM 账号(accid),最大长度 32 字符,必须保证一个应用内唯一
isOffline boolean 广播消息是否存离线,true 或 false,默认 false
ttl int 存离线状态下的有效期,单位小时,默认 7 天
targetOs Array 目标客户端,默认所有客户端,JSONArray,格式:["ios","aos","pc","web","mac"]

返回参数

参数 类型 说明
msg JSON 广播消息,具体包含信息参见下表

msg 的成员参数说明:

参数 类型 说明
broadcastid Long 广播消息的 ID,应用内唯一
from String 发送者的云信 IM 账号
body String 广播消息内容
targetOs JSONArray 目标客户端,示例:["ios","aos","pc","web","mac"]
isOffline boolean 广播消息是否存离线
createTime Long 广播消息创建时间
expireTime Long 广播消息过期时间

示例

cURL请求示例

curlcurl -X POST -H "AppKey: go9dnk49**3mgq3" -H "Nonce: 4tgg**23t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&body=abc' 'https://api.netease.im/nimserver/msg/broadcastMsg.action'

请求成功返回示例

http 响应:json

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "msg": {
        "expireTime": 1505502793520,
        "body": "abc",
        "createTime": 1505466793520,
        "isOffline": true,
        "broadcastId": 48174937359009,
        "targetOs": [
            "ios",
            "pc",
            "aos"
        ]
    }
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"ttl exceeds"  // ttl 字段超出最大限制
}

状态码

该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码

状态码 说明 处理建议
403 导致请求失败的原因可能为:
  • 应用专属集群检查不通过
  • 应用不可用
查看对应提示信息做出处理
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 调用频率超限 降低调用频率
500 服务出错 -

删除单条广播消息

API 使用限制

单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。

URL

POST  https://api.netease.im/nimserver/history/delBroadcastMsgById.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

  • POST 请求中 Headers 的设置请参考API调用方式
  • POST 请求中 Body 的设置如下:
参数类型必须说明
broadcastId Long 广播消息 ID,应用内唯一

示例

请求示例(curl)

curlcurl -X POST -H "appkey: fe416***d2547" -H "nonce: 12345" -H "curtime: 1459154905" -H "checksum: 8d3ef***5fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'broadcastId=123456' "https://api.netease.im/nimserver/history/delBroadcastMsgById.action"

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200
} 

状态码

该接口在 HTTPS Body 中返回状态码,状态码详情请参见状态码

此文档是否对你有帮助?
有帮助
去反馈
  • 发送广播消息
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码
  • 删除单条广播消息
  • API 使用限制
  • URL
  • 请求参数
  • 示例
  • 请求示例(curl)
  • 返回示例
  • 状态码