服务端
API 参考
圈组

发送消息

更新时间: 2024/05/24 15:45:01

云信服务端提供 API,支持发送圈组的消息。调用时,可配置消息所属的服务器和频道、消息类型、消息内容、离线推送文案、是否存云端历史、是否@人、是否对消息进行内容审核、是否抄送、是否配置为对 Thread 中某条消息的回复等。

功能介绍

本 API 主要支持发送的消息类型包括文本消息、图片消息、语音消息、视频消息、文件消息、提示消息、地理位置消息和自定义消息。同时支持如下功能:

功能
说明
存云端历史 圈组消息默认存云端历史且支持查询,具体查询方式请参见云端历史消息查询
@ 功能 @ 某些人、@ 频道内所有人、@ 某些身份组,具体见下文带 mention 关键字的参数
未读数 每个频道上的 消息未读数 默认最多显示为 99+。可在云信控制台配置最大未读数(在云信控制台选择应用,进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 所有未读消息(包括@)的消息计数即可配置)。
  • @消息未读数量的有效期默认为 7 天。
  • 可在云信控制台配置 @消息未读数的有效期(在云信控制台选择应用,进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 未读的@消息数-周期即可配置)。
  • 发送给游客的消息,不支持展示未读数。
离线推送 指定离线推送文案和离线推送的 payload。需确保已通过 SDK 完成圈组的离线推送配置,具体参见圈组 Android 离线推送圈组 APNs 离线推送
会话消息回复
(Thread)
指定与 Thread 相关的配置信息,发送一条引用某条消息的回复。Thread 指以一条消息作为根消息的消息回复树状结构。具体相关参数请参见下文请求参数表格中带reply和thread关键字的参数)。更多概念性介绍,请参见会话消息回复(Thread)功能介绍圈组的会话消息回复 (Thread)功能为增值功能,需要在开通圈组后再额外开通才能使用和生效,且开通后只能在圈组内使用,相关接口和 IM 其他模块的不同。可在云信控制台开通该功能(在云信控制台选择应用,进入IM 即时通讯 > 功能配置 > 圈组 > 子功能配置 > 会话消息回复即可配置)。
内容审核 配置内容审核相关参数,对消息内容进行内容审核。具体参数说明,见下文的useYidun、antispam、antispamCustom、bid、yidunAntiCheating和yidunAntiSpamExt。更多相关介绍,参见圈组内容审核中的背景信息前提条件
消息抄送 指定消息是否需要抄送(见下文routeEnable),并可指定需要将消息抄送到的服务器的地址(见下文env参数)。更多相关介绍,参见消息抄送服务概述

下行消息量(云信服务端发送至客户端的消息)为计费特征, 下行消息包含客户端主动拉取的历史消息和在线期间收到的消息。

调用限制

限制类型
说明
调用时机 发送消息前请确保已通过服务端 API 或 SDK API 在圈组服务器下创建频道。圈组消息只能在频道内发送。
功能开通 消息抄送、内容审核和会话消息回复(Thread) 的配置,均需在开通圈组功能后再额外开通才能使用。
特殊场景限制 如果需要实现会话消息回复(Thread),即引用某条消息进行回复,相关的 8 个可选参数都 必须传入相应的值,不能为空,否则无法回复成功。具体见下文的Thread 配置场景示例

URL

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

请求参数

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

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

参数

类型

是否必须

说明

from

String

消息发送者的用户账号(accid)

发送者需要拥有“发送消息的权限”,否则将返回 403 错误码。权限通过身份组管控。

serverId

long

服务器 ID

channelId

long

频道 ID

type

int

消息类型

  • 0:文本消息,消息内容为普通文本
  • 1:图片消息,消息内容为图片 URL 地址、尺寸、图片大小等信息
  • 2:语音消息,消息内容为语音文件的 URL 地址、时长、大小、格式等信息
  • 3:视频消息,消息内容为视频文件的 URL 地址、时长、大小、格式等信息
  • 4:地理位置消息,消息内容为地理位置标题、经度、纬度信息
  • 6:文件消息,消息内容为文件的 URL 地址、大小、格式等信息,格式不限
  • 10:提示消息,又叫做 Tip 消息,没有离线推送和通知栏提醒,主要用于圈组内的通知提醒,例如频道内聊天过程中命中敏感词后的提示消息等场景
  • 100:自定义消息,开发者自定义的消息类型,例如红包消息、石头剪子布等形式的消息如果您的应用未开通安全通(即易盾反垃圾)功能,自定义消息不会提交内容安全检测。

body

String

消息内容,最大 5,000 字符
文本或提示消息请在 body 字段填写消息内容的文案; 其它类型消息,请填写 attach 字段
消息格式请参考 消息格式示例

attach

String

消息附件,最大5,000字符

ext

String

扩展字段,最大1,024字符

msgIdClient

String

客户端消息ID

pushContent

String

推送文案,最长 500 个字符。具体参见 推送配置参数详解。

pushPayload

JSON

推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置

option

JSON

发送消息时特殊指定的行为选项, JSON 格式,可用于指定消息的存云端历史,推送等特殊行为; option 中字段不填时表示默认值,option示例:

{"push":false,"history":false,"badge":false,"needPushNick":true}

字段说明:

  • history:该消息是否存云端历史,默认 true;
  • push:该消息是否需要 APNS 推送或安卓系统通知栏推送,默认 true
  • badge:该消息是否需要计入到未读计数中,默认 true
  • needPushNick:推送文案是否需要带上昵称,不设置该参数时默认 true
  • routeEnable:是否需要抄送, 0: 不需要, 1: 需要, 默认 1

mentionedAll

int

是否 @所有人,0 或 1,1 表示 @所有人。如果传 1,需要拥有 @所有人的权限才能生效,否则将报错 403

mentionedRoleidList

JSON Array

被 @ 的身份组列表,最多@ 10 个身份组。如果 mentionedAll=1,则本参数无效需要拥有 @身份组的权限才能生效,否则将报错 403

mentionedAccidList

JSON Array

@ 的用户账号(accid)列表,最大 100 个,如果 mentionedAll=1 或 mentionedRoleidList 不为空,则本参数无效需要拥有 @某些人的权限才能生效,否则将报错 403

env

String

当前消息需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称(如下图),最大 32 个字符

replyMsgFromAccount

String

被回复的消息(假设为消息1)的发送者账号。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

replyMsgTime

long

被回复的消息(假设为消息1)的发送时间。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

replyMsgIdServer

long

被回复的消息(假设为消息1)的服务端消息 ID。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

replyMsgIdClient

String

被回复的消息(假设为消息1)的客户端消息 ID。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

threadMsgFromAccount

String

被回复的消息(假设为消息1)所属 Thread 的根消息的发送者账号。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

threadMsgTime

long

被回复的消息(假设为消息1)所属 Thread 的根消息的发送时间。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

threadMsgIdServer

long

被回复的消息(假设为消息1)所属 Thread 的根消息的服务端消息 ID。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

threadMsgIdClient

String

被回复的消息(假设为消息1)所属 Thread 的根消息的客户端消息 ID。如果需要回复消息1,则该参数必传。场景示例见下文的Thread配置场景示例

useYidun

String

0:在开通安全通(即易盾反垃圾)的情况下,不将消息提交给易盾进行内容审核(包括自定义消息)

若不填此字段,即在默认情况下,若应用开通了安全通,则使用安全通来进行内容审核

antispam

String

 对于开通了安全通(即易盾反垃圾)的应用,本消息是否需要指定经由易盾检测的内容(antispamCustom)。

 true或false, 默认false。

只对消息类型为 100 的消息(即自定义消息)生效。

antispamCustom

String

自定义的反垃圾检测内容, JSON格式,长度限制同 body 字段,不能超过 5000 字符。在 antispam 参数为 true 时生效。要求antispamCustom格式如下:

{"type":1,"data":"custom content"}

字段说明:

type: 1:文本,2:图片。

data:文本内容或图片 URL 地址。

bid

String

安全通的自定义反垃圾(即内容审核)业务的 ID。自定义反垃圾业务主要用来针对圈组的资料信息进行除了默认反垃圾业务以外的内容审核开通安全通后,云信控制台会自动生成默认反垃圾业务。您的应用不需要配置业务 ID 就能默认采用安全通的默认反垃圾业务,如果需要自定义反垃圾业务,请先通过云信官网首页提供的微信、在线聊天和电话等方式跟商务经理发出申请,获取对应的业务 ID。

yidunAntiCheating

String

可选,易盾反垃圾含圈组反作弊专属字段,限制 JSON 格式,长度限制1024,具体请参见文本防刷版开发文档

yidunAntiSpamExt

String

可选,易盾反垃圾扩展字段,限制 JSON 格式,长度限制1024,具体请参见易盾的反垃圾含圈组版用户可扩展参数

返回参数

参数
类型
说明
code int 状态码,表示请求结果状态,如返回 200 则表示请求成功
data String 发送出的消息数据

其中 data 包含的参数如下:

参数
类型
说明
time String 消息发送时间
msgIdClient String 客户端的消息 ID
msgIdServer String 云信服务端的消息 ID
antispam String 自定义消息是否经由易盾进行内容审核,false:不审核

安全通的内容审核结果相关字段信息,请参见审核结果字段说明

示例

cURL请求示例

curlcurl -X POST -H "AppKey: go9dnk49bk**0803mgq3" -H "Nonce: 4tggg**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&type=0&serverId=1&channelId=1&body=abc' 'https://api.netease.im/nimserver/qchat/sendMsg.action'

返回示例

HTTP 响应:JSON

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
    "data": {
        "time": 112121,
        "msgIdClient": "sasas",
        "msgIdServer": 123,
        "antispam": false
     }
}

Thread配置场景示例

以上图所示 Thread 的回复场景为例

  • 假设需要发送消息C1 回复消息 B1,Thread 相关的请求参数配置如下:

    参数

    类型

    是否必填

    说明

    该场景需传入的值

    replyMsgFromAccount

    String

    被回复的消息的发送方的账号

    消息B1 的发送者账号


    该场景下“被回复的消息”为消息B1

    replyMsgTime

    long

    被回复的消息的发送时间

    消息B1 的发送时间

    replyMsgIdServer

    long

    被回复的消息的服务端消息 ID,即云信服务端给出的该消息的 ID

    消息B1 的服务端消息 ID

    replyMsgIdClient

    String

    被回复的消息的客户端消息 ID,即 SDK 给出的该消息的 ID

    消息B1 的客户端消息 ID

    threadMsgFromAccount

    String

    根消息的发送方的账号

    消息A 的发送者账号


    该场景下消息A 为该 Thread 的“根消息”

    threadMsgTime

    long

    根消息的发送时间

    消息A 的发送时间

    threadMsgIdServer

    long

    根消息的服务端消息 ID,即云信服务端给出的该消息的 ID

    消息A 的服务端消息 ID

    threadMsgIdClient

    String

    根消息的客户端消息 ID,即 SDK 给出的该消息的 ID

    消息A 的客户端消息 ID

  • 假设需要发送消息B1 回复消息 A,Thread 相关的请求参数配置如下:

    参数

    类型

    是否必填

    说明

    该场景需传入的值

    replyMsgFromAccount

    String

    被回复的消息的发送方的账号

    消息A 的发送者账号


    该场景下“被回复的消息”为消息A

    replyMsgTime

    long

    被回复的消息的发送时间

    消息A 的发送时间

    replyMsgIdServer

    long

    被回复的消息的服务端消息 ID,即云信服务端给出的该消息的 ID

    消息A 的服务端消息 ID

    replyMsgIdClient

    String

    被回复的消息的客户端消息 ID,即 SDK 给出的该消息的 ID

    消息A 的客户端消息 ID

    threadMsgFromAccount

    String

    根消息的发送方账号

    消息A 的发送者账号


    该场景下,消息A 既为“被回复的消息”,也为“根消息”

    threadMsgTime

    long

    根消息的发送时间

    消息A 的发送时间

    threadMsgIdServer

    long

    根消息的服务端消息 ID,即云信服务端给出的该消息的 ID

    消息A 的服务端消息 ID

    threadMsgIdClient

    String

    根消息的客户端消息 ID,即 SDK 给出的该消息的 ID

    消息A 的客户端消息 ID

状态码

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

状态码 说明 处理建议
200 请求成功 -
403 非法操作或没有权限
  • 检查是否已开通圈组功能
  • 检查是否拥有相应的权限,如 @ 权限和发送消息的权限
  • 检查消息中是否包含违规或敏感内容。如果已开通安全通且被检测到存在违规或敏感信息,可能会被安全通的内容审核判定为“不通过”
404 对象不存在
  • 检查是否存在必传参数为空的问题
  • 检查传入的账号、服务器 ID、频道 ID 或自定义反垃圾业务 ID (bid)等是否存在
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 调用频率超限 降低调用频率
431 HTTP 重复请求 -
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 调用限制
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • cURL请求示例
  • 返回示例
  • Thread配置场景示例
  • 状态码