网易云信服务端支持发送单聊消息和群聊消息，消息类型包括文本消息、图片消息、语音消息、视频消息、地理位置消息、文件消息、提示消息和自定义消息。各类消息及相关功能的更多介绍，请参考 消息概述。

本文介绍如何使用服务端 API 发送一条单聊/群聊消息，以及不同类型消息的格式示例。

功能描述

向某个用户或者某个群组发送一条消息。

API 使用限制

单个应用默认最高调用频率请参考 频控说明。

请求 URL

httpPOST https://api.yunxinapi.com/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	是	0：文本消息 1：图片消息 2：语音消息 3：视频消息 4：地理位置消息 6：文件消息 10：提示消息 100：自定义消息， 对于未开通 安全通（即易盾反垃圾）功能的应用，自定义消息不会过内容审核。
body	String	是	消息内容，JSON 格式，具体请参考 消息格式示例 该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限
msgDesc	String	否	消息描述文本，对文本消息和提示消息以外的消息类型有效，最大长度 500 字符。该描述信息可用于云端历史消息关键词检索
antispam	boolean	否	已开通 安全通 的前提下，是否对自定义消息的指定内容（antispamCustom）进行反垃圾检测，默认 false 该参数只对自定义消息（消息类型为：100）生效。
antispamCustom	String	否	在 antispam 参数为 true 时生效 自定义的需要过反垃圾检测的内容, JSON 格式，长度限制同 body 字段，不能超过 5000 字符，要求 antispamCustom 格式如下： {"type":1, "data":"custom content"} 字段说明： type：1：文本，2：图片 data：文本内容或图片地址
option	String	否	发消息时特殊指定的行为选项,JSON 格式，可用于指定消息的漫游、存云端历史、发送方多端同步、推送、消息抄送等特殊行为。option 中字段不填时表示默认值，option 示例: {"push":false, "roam":true, "history":false, "sendersync":true, "route":false, "badge":false, "needPushNick":true} 字段说明： roam：该消息是否需要漫游，默认 true（需要已为应用开通漫游消息功能） history：该消息是否存云端历史，默认 true sendersync：该消息是否需要发送方多端同步，默认 true。如果发送方多端同时登录在线，则该消息发送后会同步到在线的其他端 push：该消息是否需要 APNs 推送或 Android 系统通知栏推送，默认 true route：该消息是否需要抄送至指定的应用服务器。默认 true (需要已为应用 开通消息抄送功能); badge：该消息是否需要计入到未读计数中，默认 true; needPushNick：推送文案是否需要带上昵称，不设置该参数时默认 true persistent：是否需要存离线消息，不设置该参数时默认 true。离线消息指不在线时其他人发来的消息。如果存离线，在用户下次登录时，IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端 SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息，且每个会话最多 100 条最新的离线消息。群聊场景下发最近 30 天内的离线消息，且每个群聊会话最多下发 100 条最新的离线消息。 sessionUpdate：是否将本消息更新到服务端会话列表中本会话的最后一条消息（lastmsg），默认 true。
pushcontent	String	否	推送文案，最长 500 字符。option 选项中允许推送（push=true）后才能配置推送文案。pushcontent 如果不填，则使用默认文案。推送文案的显示规则如下： pushcontent 不为空且 needPushNick=true，最终推送文案为：推送者昵称+pushcontent pushcontent 不为空且 needPushNick=false，最终推送文案为：pushcontent pushcontent 为空且 needPushNick=true，最终推送文案为：推送者昵称+默认文案 pushcontent 为空且 needPushNick=false，最终推送文案为：默认文案 其中，根据消息类型，默认文案分为以下几种： 文本消息默认文案：发来了一条消息 地理位置默认文案：发来了一个地理位置 语音消息默认文案：发来了一段语音 视频消息默认文案：发来了一段视频 文件消息默认文案：发来了一个文件 图片消息默认文案：发来了一张图片 语音聊天邀请消息默认文案：发来了语音聊天邀请 视频聊天邀请消息默认文案：发来了视频聊天邀请
payload	String	否	推送对应的 payload，必须是 JSON 格式，不能超过 2048 字符。更多说明请参考 推送 payload 配置
ext	String	否	开发者扩展字段，必须是 JSON 格式，该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限
forcepushall	boolean	否	发送群消息时，强推（@操作）列表是否为群里除发送者外的所有有效成员，默认为 false
forcepushlist	String	否	发送群消息时的强推（@操作）用户列表，格式为 JSONArray，如["accid1", "accid2"]。若 forcepushall 为 true，则 forcepushlist 为除发送者外的所有有效群成员 最多可强推 100 个用户，如果超过将报错（状态码：811）。
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 字符（具体请参考 易盾的反垃圾防刷版专属字段） 反作弊相关的 email、phone、token、extension，抄送到 yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt。 yidunAntiSpamExt 传入的值默认覆盖 extension。
yidunAntiSpamExt	String	否	透传给易盾的反垃含圈组版的检测参数，格式为 JSON，长度限制 1024 字符（具体请参考 易盾的反垃圾含圈组版用户可扩展字段） 反作弊相关的 email、phone、token、extension，抄送到 yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt。
markRead	int	否	群消息是否需要已读业务（仅对群消息有效），0:不需要，1:需要
async	boolean	否	是否异步，默认 false
checkFriend	boolean	否	是否为好友关系才能发送消息，默认为 false 如需设置为好友关系才能发送消息，需先在 网易云信控制台 完成如下配置。 单击展开查看具体配置 选择应用，进入应用详情界面。 在应用详情界面的IM 即时通讯区域，选择功能配置 > 基础功能 >单聊消息配置，将非好友关系是否允许发送消息设置为不允许。
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.yunxinapi.com/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
}