发送消息
更新时间: 2024/07/17 17:57:34
网易云信服务端支持发送单聊消息和群聊消息,消息类型包括文本消息、图片消息、语音消息、视频消息、地理位置消息、文件消息、提示消息和自定义消息。各类消息及相关功能的更多介绍,请参考 消息概述。
本文介绍如何使用服务端 API 发送一条单聊/群聊消息,以及不同类型消息的格式示例。
功能描述
向某个用户或者某个群组发送一条消息。
API 使用限制
单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
请求 URL
httpPOST https://api.netease.im/nimserver/msg/sendMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求 Body 参数
-
POST 请求中 Headers 的设置请参考 API 调用方式。
-
POST 请求中 Body 的设置如下:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
from | String | 是 |
发送者的网易云信 IM 账号(accid),最大 32 字符, 必须保证一个应用内唯一 |
ope | int | 是 | 仅可传入 0 或 1,0:单聊消息,1:群消息(高级群),传入其他值都将报错(状态码:414) |
to | String | 是 | 消息的接收方,ope 为 0 时需填入接收消息用户的的网易云信 IM 账号(accid),ope 为 1 时需填入接收消息的群的 ID(即 tid),最大 32 字符 |
type | int | 是 |
|
body | String | 是 | 消息内容,最大长度 5000 字符,JSON 格式,具体请参考 消息格式示例 |
msgDesc | String | 否 | 消息描述文本,对文本消息和提示消息以外的消息类型有效,最大长度 500 字符。该描述信息可用于云端历史消息关键词检索 |
antispam | boolean | 否 | 已开通 安全通 的前提下,是否对自定义消息的指定内容(antispamCustom)进行反垃圾检测,默认 false |
antispamCustom | String | 否 | 在 antispam 参数为 true 时生效 自定义的需要过反垃圾检测的内容, JSON 格式,长度限制同 body 字段,不能超过 5000 字符,要求 antispamCustom 格式如下: {"type":1, "data":"custom content"} 字段说明: |
option | String | 否 |
发消息时特殊指定的行为选项,JSON 格式,可用于指定消息的漫游、存云端历史、发送方多端同步、推送、消息抄送等特殊行为。option 中字段不填时表示默认值,option 示例: {"push":false, "roam":true, "history":false, "sendersync":true, "route":false, "badge":false, "needPushNick":true} 字段说明:
|
pushcontent | String | 否 |
推送文案,最长 500 字符。option 选项中允许推送(push=true)后才能配置推送文案。pushcontent 如果不填,则使用默认文案。推送文案的显示规则如下:
|
payload | String | 否 | 推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参考 推送 payload 配置 |
ext | String | 否 | 开发者扩展字段,必须是 JSON 格式,长度限制 1024 字符 |
forcepushall | boolean | 否 | 发送群消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,默认为 false |
forcepushlist | String | 否 |
发送群消息时的强推(@操作)用户列表,格式为 JSONArray,如["accid1", "accid2"]。若 forcepushall 为 true,则 forcepushlist 为除发送者外的所有有效群成员
|
forcepushcontent | String | 否 | 发送群消息时,针对强推列表 forcepushlist 中的用户,强制推送的内容,最大 500 字符 |
useYidun | int | 否 |
单条消息(包括自定义消息)是否使用 安全通(即易盾反垃圾),只能传 0,传其他值相当于不传 0:(在已开通安全通的情况下)本条消息不使用安全通检测 若不填此字段,即在默认情况下,若应用开通了安全通,则使用安全通来进行反垃圾检测 |
bid | String | 否 |
安全通业务 ID,可以指定当前消息过安全通某个检测策略。 默认情况下网易云信控制后台会生成默认业务,开通安全通后,客户端不需要配置业务 ID 就能默认走该策略,若需要自定义检测策略,请 [提交工单](https://app.yunxin.163.com/global/service/ticket/create) 联系网易云信技术支持工程师进行配置,配置好后传入对应的安全通业务 ID,表示当前消息过安全通的指定检测策略。 |
yidunAntiCheating | String | 否 |
透传给易盾的反作弊检测参数,格式为 JSON,长度限制 1024 字符(具体请参考 易盾的反垃圾防刷版专属字段)
|
yidunAntiSpamExt | String | 否 |
透传给易盾的反垃含圈组版的检测参数,格式为 JSON,长度限制 1024 字符(具体请参考 易盾的反垃圾含圈组版用户可扩展字段)
|
markRead | int | 否 | 群消息是否需要已读业务(仅对群消息有效),0:不需要,1:需要 |
async | boolean | 否 | 是否异步,默认 false |
checkFriend | boolean | 否 |
是否为好友关系才能发送消息,默认为 false单击展开查看具体配置
|
subType | int | 否 | 自定义消息子类型,大于 0 |
msgSenderNoSense | int | 否 |
发送方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息发送者无该消息的多端、漫游、历史记录等
|
msgReceiverNoSense | int | 否 |
接受方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息接收者者无该消息的多端、漫游、历史记录等
|
env | String | 否 | 当前消息需要抄送到的环境的名称,对应您在 网易云信控制台 中配置的自定义抄送的环境名称(如下图),最大 32 个字符, |
robotAccount | String | 否 | 机器人账号,对应控制台提前设置好的机器人 仅在群聊中有效,点对点聊天室中该字段会被忽略 |
robotTopic | String | 否 | 机器人消息话题 |
robotFunction | String | 否 | 机器人具体功能 |
robotCustomContent | String | 否 | 机器人自定义内容 |
若需要使用机器人消息功能,需要提前在 网易云信控制台 开通并设置机器人。
返回参数
参数 | 类型 | 说明 |
---|---|---|
data | JSON | 消息数据,具体见下表 |
data 的成员参数说明如下:
参数 | 类型 | 说明 |
---|---|---|
msgid | Long | 消息 ID option 中 persistent 参数为 false (表示不需要保存离线消息),由于不保存数据库,所以会返回 "msgid":0 。这并不影响 SDK 正常接收该消息。 |
antispam | boolean | 消息是否被反垃圾(内容审核)拦截,如未被拦截则值为 false |
timetag | Long | 消息发送的时间戳 |
示例
cURL 请求示例
cURLcurl -X POST -H "AppKey: go9dnk4**0803mgq3" -H "Nonce: 4tggge** 23t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&ope=0&to=lisi&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendMsg.action'
请求成功返回示例
JSON"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"data": {
"msgid": 1200510468189,
"timetag": 1545635366312, //消息发送的时间戳
"antispam": false
}
}
请求失败返回示例
JSON"Content-Type": "application/json; charset=utf-8"
{
"code":414
"desc":"check ope" // ope 参数不是 0 或 1
}
JSON"Content-Type": "application/json; charset=utf-8"
{
"code":423
"desc":"account 'mute'." // 发送方账号被禁言
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参考 状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
811 | 强推(@功能)forcePushList 列表的用户数超过上限 100 | 减少强推列表中的用户数 |
416 | 接口调用过于频繁 | 减少调用频率 |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
423 | 发送方账号被禁言 | 检查接收方的禁言名单里是否包含发送方 |
422 | 发送方账号被禁用 | 检查账户是否可用 |
403 | 导致请求失败的原因可能为:
|
- |
431 | 接口请求重复 | - |
500 | 服务出错 | - |
消息格式示例
文本消息(type = 0)
JSON{
"msg": "哈哈哈"//消息内容
}
图片消息(type = 1)
JSON{
"name":"图片发送于 2015-05-07 13:59", //图片 name
"md5":"9894907e4ad9de4678091277509361f7", //图片文件 md5,按照字节流加密
"url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e", //生成的 url
"ext":"jpg", //图片后缀
"w":6814, //宽,单位为像素
"h":2332, //高,单位为像素
"size":388245 //图片文件大小,单位为字节(Byte)
}
语音消息(type = 2)
JSON{
"dur":4551, //语音持续时长 ms
"md5":"87b94a090dec5c58f242b7132a530a01", //语音文件的 md5 值,按照字节流加密
"url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9", //生成的 url
"ext":"aac", //语音消息格式
"size":16420 //语音文件大小,单位为字节(Byte)
}
视频消息(type = 3)
JSON{
"dur":8003, //视频持续时长 ms
"md5":"da2cef3e5663ee9c3547ef5d127f7e3e", //视频文件的 md5 值,按照字节流加密
"url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412", //生成的 url
"w":360, //宽,单位为像素
"h":480, //高,单位为像素
"ext":"mp4", //视频格式
"size":16420 //视频文件大小,单位为字节(Byte)
}
地理位置消息(type = 4)
JSON{
"title":"中国 浙江省 杭州市 网商路 599 号", //地理位置 title
"lng":120.1908686708565, // 经度
"lat":30.18704515647036 // 纬度
}
文件消息(type = 6)
JSON{
"name":"BlizzardReg.ttf", //文件名
"md5":"79d62a35fa3d34c367b20c66afc2a500", //文件 MD5,按照字节流加密
"url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //文件 URL
"ext":"ttf", //文件后缀类型
"size":91680 //大小,单位为字节(Byte)
}
提示消息(type = 10)
JSON{
"msg": "您收到一份礼物"
}
自定义消息(type = 100)
JSON//开发者自定义的 body,JSON 格式
{
"myKey":myValue
}
此文档是否对你有帮助?