API 参考
圈组

发送超大群消息

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

本文介绍如何通过 API 在超大群中发送消息(包括文本,图片,语音,视频和地理位置等),并在 SDK 端成功接收。

前提条件

通过 IM 服务端 API 发送群消息前,请确保:

  • 已通过 IM 服务端 API 创建超大群,并获取超大群 ID(tid)。
  • 消息发送方和接收方已加入同一个超大群。

实现超大群消息收发

时序图

以下时序图仅以 “发送方为超大群创建者,且创建超大群和拉人入群均通过调用服务端 API 实现” 这个场景为例,展示实现超大群消息收发的流程。

uml diagram

实现流程

本节仅对上述时序图中标为橙色的流程步骤进行详细说明。其他流程步骤请参考相关服务端 API 文档或 SDK 文档。

  1. 接收方注册对应平台/框架 SDK 的消息监听接口,监听 IM 服务端投递至 SDK 端的超大群消息。

    平台/框架 超大群消息监听接口
    Android observeReceiveMessage
    iOS onRecvMessages:
    Web
    • NIM Web SDK:监听onMsg事件
    • 增强版 NIM Web SDK:监听msg事件
    Windows/macOS
    Flutter onMessage

    注册消息接收监听接口相关示例代码,请参见各平台/框架 SDK 文档的对应章节。

  2. 发送方调用 superteam/sendMsg.action 发送超大群消息,具体参数和示例请参考下文。

  3. IM 服务端将群聊消息投递至 SDK 端,SDK 端触发群聊消息接收回调,将群聊消息投递至接收方。

发送超大群消息

API 使用限制

  • 单个应用最高调用频率:100 次/秒,超过返回 416 错误码。
  • 当超大群人数级别大于 2000 人时,还会根据 tid 做流控处理,10 次/秒,超过返回 416 错误码。

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考接口概述
  • POST 请求中 Body 的设置如下:
参数类型必填说明
tidLong云信服务器产生,创建超大群时会返回,最大长度 64 位长整型
fromAccidString消息发送者账号,accid,必须是超大群成员,最大长度 32 位字符
typeInteger消息类型
0,文本消息;1,图片;2,语音;3,视频;4,地理位置信息;6,文件;10,提示;100,自定义消息类型对于未对接易盾反垃圾功能的应用,该类型的消息不会提交反垃圾系统检测
bodyString消息内容,JSON,最大长度 5000 位字符
具体请参考:消息格式示例
msgDescString消息描述文本,针对非 Text、Tip 类型的消息有效,最大长度 500 位字符
该描述信息可用于云端历史消息关键词检索
antispam Boolean对于已对接易盾反垃圾功能的应用,本消息是否需要指定经由易盾检测的内容(antispamCustom)
true 或 false,默认 false。
只对消息类型为自定义消息类型(100)的消息生效
antispamCustom String自定义的反垃圾检测内容, JSON,长度限制同 body 字段,不能超过 5000 位字符
在 antispam 参数为 true 时才生效,要求 antispamCustom 的格式如下:
{"type":1,"data":"custom content"}
字段说明:
type: 1:文本,2:图片
data: 文本内容或图片地址
useYidun Integer单条消息是否使用易盾反垃圾
0:(在开通易盾的情况下)不使用易盾反垃圾,包括自定义消息。
若不填此字段,即在默认情况下,若应用开通了易盾反垃圾功能,则使用易盾反垃圾来进行垃圾消息的判断。
yidunAntiCheating String 易盾反垃圾增强反作弊专属字段,JSON,最大长度 1024 位字符
具体请参见易盾反垃圾防刷版专属字段反作弊相关的 email、phone、token、extension,抄送到 yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt
yidunAntiSpamExt String 易盾反垃圾扩展字段,JSON,最大长度 1024 位字符反作弊相关的 email、phone、token、extension,抄送到 yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt
bidString易盾反垃圾业务 ID,实现“单条消息配置对应的反垃圾业务规则”,若不填则使用原来的反垃圾配置
option String发消息时特殊指定的行为选项,JSON,可用于指定消息的漫游,存云端历史,发送方多端同步,消息抄送等特殊行为;不填时表示默认值,参考示例:
{"roam":true,"history":false,"sendersync":true,"route":false}
字段说明:
1. roam: 该消息是否需要漫游,默认true(需要 app 开通漫游消息功能);
2. history: 该消息是否存云端历史,默认 true;
3. sendersync: 该消息是否需要发送方多端同步,默认 true;
4. route: 该消息是否需要抄送第三方;默认 true(需要 app 开通消息抄送功能);
5. persistent: 是否需要存离线消息,不设置该参数时默认 true;
6. push: 该消息是否需要推送,默认 true;
7. badge: 该消息是否需要计入到未读计数中,默认 true;
8. needPushNick: 推送文案是否需要带上昵称,默认 true;
9. sessionUpdate: 是否将本消息更新到服务端会话列表中本会话的最后一条消息,不设置时默认true
ext String开发者扩展字段,最大长度 1024 位字符
pushContent String推送内容,最大长度 500 位字符
pushPayload String推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置
isForcePush Boolean发送消息时,是否强制推送,默认 true
forcePushContent String发送消息时,强制推送的内容,最大长度 500 位字符
forcePushAll Boolean发送消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,默认 false
forcePushList String发送消息时,强推(@操作)列表,JSONArray,如["accid1","accid2"],最多 100 人
subType String消息子类型,大于 0
env String所属环境,可以配置不同的抄送地址,最大长度 32 位字符
isCheckMute Boolean发送群消息时,是否检查与群相关禁言
true,检查(默认);false,不检查,如不检查,群内被禁言的用户可以发送消息

返回参数

参数 类型 说明
code Integer 状态码
data String 消息详情,包括消息的 ID,发送时间戳以及是否通过反垃圾

示例

请求示例(curl)

curlcurl -X POST -H 'AppKey: 45c6af**51215d0bdd6e'  -H 'CheckSum: 29bfd78a5b1f63e154736a41b40233d7475ac944'  -H 'CurTime: 1499242027284'  -H 'Nonce: 58D85128FF' -H 'Content-Type: application/x-www-form-urlencoded' -d 'fromAccid=user01&tid=2576209540&type=0&body=%7B%22msg%22%3A%22%E5%93%88%E5%93%88%E5%93%88%22%7D' https://api.netease.im/nimserver/superteam/sendMsg.action

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "data":{
        "msgid": 1234,  
        "timetag": 12345,  
        "antispam": false  
    }
    "code": 200
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code": 811,
    "desc": "param forcePushList exceed limit"  // forcePushList人数超过限制
}

状态码

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

状态码 说明 处理建议
200 请求成功 -
403 禁止操作:
  • 发送者不是群成员
  • 超大群功能未开通
  • app 权限错误
    根据对应提示信息做出处理
    404 超大群不存在 -
    414 参数错误 根据提示信息,检查传入参数的格式和限制条件
    416 调用频率超出限制 降低访问频率
    422 发送者账户不合法 -
    423 发送者被禁言 -
    500 服务出错 -
    811 forcePushList 人数超过限制 减少 forcePushList 中传入的人数
    812 整个群被禁言:
    发送方为普通成员,且普通成员被禁言
    -
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 前提条件
    • 实现超大群消息收发
    • 发送超大群消息
    • API 使用限制
    • URL
    • 请求参数
    • 返回参数
    • 示例
    • 请求示例(curl)
    • 请求成功返回示例
    • 请求失败返回示例
    • 状态码