发送消息 - IM 即时通讯

在线调试

开发者中心

IM 即时通讯

服务端 API

发送消息

更新时间： 2024/08/22 15:10:07

网易云信服务端支持发送单聊消息和群聊消息，消息类型包括文本消息、图片消息、语音消息、视频消息、地理位置消息、文件消息、提示消息和自定义消息。

功能描述

各类消息及相关功能的更多介绍，请参考消息概述。
该接口可以在会话中发送一条单聊/群聊消息。会话类型包括单聊、群聊、超大群会话。聊天室消息发送请参考发送聊天室消息。
自 V10.4.0 起，支持发送群定向消息。即发送群消息时，可以指定接收消息的群成员列表。

调用频率

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

请求

URL

POST https://open.yunxinapi.com/im/v2/conversations/:{conversation_id}/messages

请求 Header 的参数说明请参考请求 Header。

路径参数

参数名称	类型	是否必选	说明	示例
`conversation_id`	String	必选	会话 ID。会话 ID 需要用户自行拼装，拼装规则： `owner_id \| conversation_type \| other_id` 或 `owner_id \| conversation_type \| team_id` owner_id：操作者账号 ID conversation_type：会话类型，1：单聊会话。2：高级群会话。3：超大群会话 other_id：对方账号 ID（单聊对话） team_id：群组 ID（群组会话）	单聊会话：`Accid1 \| 1 \| Accid2` 高级群会话：`Accid1 \| 2 \| tid` 超大群会话：`Accid1 \| 3 \| tid`

请求体参数

参数名称	类型	是否必选	描述
+ `message`	Object	必选	消息体。
`message_type`	Integer	必选	消息类型。 0：文本消息 1：图片消息 2：语音消息 3：视频消息 4：地理位置消息 6：文件消息 10：提示消息 100：自定义消息对于未开通安全通（即网易易盾反垃圾）功能的应用，自定义消息不会过内容审核。
`sub_type`	Integer	可选	自定义消息子类型，大于 0。message_type = 100 时该字段才有效。
`text`	String	可选	对于文本消息和提示消息，该字段必填，值为消息内容，长度上限 5000 位字符。对于非文本/提示消息，该字段非必填，值为描述信息，可用于全文关键字搜索历史消息，长度上限 500 位字符。
`attachment`	Object	可选	非文本消息/提示消息的属性或自定义消息内容，长度上限 5000 位字符。对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。
+ `message_config`	Object	可选	消息配置项。
`unread_enabled`	Boolean	可选	该消息是否需要计入未读数。默认为 true（计入）。
`mutil_sync_enabled`	Boolean	可选	该消息是否需要发送方多端同步。默认为 true（同步）。
`offline_enabled`	Boolean	可选	是否需要存离线消息，默认为 true（存储）。离线消息指不在线时其他用户发来的消息。如果存离线，在用户下次登录时，IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端 SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息，且每个会话最多 100 条最新的离线消息。群聊场景下发最近 30 天内的离线消息，且每个群聊会话最多下发 100 条最新的离线消息。
`history_enabled`	Boolean	可选	该消息是否存云端历史。默认为 true（存储）。
`roaming_enabled`	Boolean	可选	该消息是否需要漫游。默认为 true（漫游）。
`conversation_update_enabled`	Boolean	可选	是否将该消息更新至会话列表服务中本会话的最后一条消息。默认为 true（更新）。
+ `target_option`	Object	可选	群定向消息配置项。该功能需要单独开通。
`receiver_account_ids`	Array of strings	必选	群定向消息成员列表，即指定接收群消息的群成员列表。当 `inclusive` 为 true，当前列表为可见（接收）列表。当 `inclusive` 为 false，当前列表为不可见（不接收）列表。列表中不能包含消息发送者，消息发送者默认为可见。列表中不能包含非法账号、非群成员账号。列表中最多可以传入 100 个用户账号。
`inclusive`	Boolean	可选	群定向消息成员列表是否为可见列表。默认为 true，即 `receiver_account_ids` 为可见（接收）列表。发送超大群消息时，不能将 `inclusive` 设置为 false。
`visible_to_new_member`	Boolean	可选	新进群成员是否可见该消息。默认为 false，即新进群成员不可以查看该定向消息。若设置为 true，则新进群成员若可以查询该定向消息，可以通过云端历史相关接口查询到该消息。当 `inclusive` 为 true 时，不能同时设置 `visible_to_new_member` 为 true。即发送定向列表为可见的定向消息时，只能由定向列表中成员接收和查看。发送超大群消息时，不能将 `visible_to_new_member` 设置为 true。
+ `route_config`	Object	可选	抄送相关配置项。
`route_enabled`	Boolean	可选	该消息是否需要抄送至指定的应用服务器（需要为应用开通消息抄送功能），默认为 true（抄送）。
`route_environment`	String	可选	当前消息需要抄送到的环境的名称，对应您在网易云信控制台中配置的自定义抄送的环境名称。
+ `push_config`	Object	可选	推送相关配置项。
`push_enabled`	Boolean	可选	该消息是否需要 APNs 推送或 Android 系统通知栏推送，默认为 true（推送）。只有该字段为 true 时，推送相关参数才会生效。
`push_nick_enabled`	Boolean	可选	推送文案是否需要带上昵称，默认为 true（带昵称）。
`push_content`	String	可选	推送文案，长度上限 500 位字符。如果不填，则使用默认推送文案。推送文案的显示规则如下： push_content 不为空且 push_nick_enabled = true，最终推送文案为：推送者昵称+ push_content push_content 不为空且 push_nick_enabled = false，最终推送文案为：push_content push_content 为空且 push_nick_enabled = true，最终推送文案为：推送者昵称+默认文案 push_content 为空且 push_nick_enabled = false，最终推送文案为：默认文案其中，根据消息类型，默认文案分为以下几种：文本消息默认文案：发来了一条消息图片消息默认文案：发来了一张图片语音消息默认文案：发来了一段语音视频消息默认文案：发来了一段视频地理位置默认文案：发来了一个地理位置文件消息默认文案：发来了一个文件语音聊天邀请消息默认文案：发来了语音聊天邀请视频聊天邀请消息默认文案：发来了视频聊天邀请
`push_payload`	String	可选	推送对应的 payload，必须是 JSON 格式，长度上限 2048 位字符。详情请参考推送 payload 配置。
`push_forcepush_enable`	Boolean	可选	该消息（群消息）是否强制推送（@操作），默认为 false。只有该字段为 true 时强制推送相关参数才会生效。
`push_forcepush_all`	Boolean	可选	该消息（群消息）是否强制推送（@操作）给群组中所有有效成员（除消息发送者），默认为 false。
`push_forcepush_ids`	Array of strings	可选	该消息（群消息）的强推（@操作）账号列表，格式为 JSONArray，如["account1","account2"]。若 push_forcepush_all 为 true，则该字段无效，该消息会强制推送（@操作）给群组中所有有效成员（除消息发送者）。最多可强推 100 个用户。
`push_forcepush_content`	String	可选	强制推送的文案，仅针对强推列表 push_forcepush_ids 中的账号，长度上限 500 位字符。
+ `antispam_config`	Object	可选	安全通相关配置项。
`antispam_enabled`	Boolean	可选	该消息（除自定义消息）是否需要过审核。若已在网易云信控制台开通安全通，该字段默认为 true（过审核），若需要设置单条消息不经过审核，则设置为 fasle。若未开通安全通，该字段无效。
`antispam_business_id`	String	可选	安全通业务 ID，可以指定当前消息过安全通某个检测策略。默认情况下网易云信控制后台会生成默认业务，开通安全通后，客户端不需要配置业务 ID 就能默认走该策略，若需要自定义检测策略，请提交工单联系网易云信技术支持工程师进行配置，配置好后传入对应的安全通业务 ID，表示当前消息过安全通的指定检测策略。
`antispam_extension`	String	可选	透传给网易易盾的反垃圾增强版的检测参数，格式为 JSON，长度限制 1024 位字符（具体请参考网易易盾的反垃圾增强版用户可扩展参数）。反作弊相关的 email、phone、token、extension，抄送到 antispam_cheating 字段中。其他用户增值信息，抄送到 antispam_extension 字段。
`antispam_cheating`	String	可选	透传给网易易盾的反作弊检测参数，格式为 JSON，长度限制 1024 位字符（具体请参考网易易盾的反垃圾防刷版专属参数）。反作弊相关的 email、phone、token、extension，抄送到 antispam_cheating 字段中。其他用户增值信息，抄送到 antispam_extension 字段。 antispam_extension 传入的值默认覆盖 extension。
`antispam_custom_message_enabled`	Boolean	可选	是否对自定义消息的指定内容（antispam_custom_message）进行审核。若已在网易云信控制台开通安全通，该字段默认为 false（不过审核），若需要设置该条自定义消息经过审核，则设置为 true。若未开通安全通，该字段无效。
`antispam_custom_message`	String	可选	自定义的安全通检测内容, JSON 格式，长度限制同 text 字段。格式如下： {"type":1,"data":"custom content"} 字段说明： type: 1 为文本。2 为图片 data: 文本内容或图片地址。该参数只对自定义消息（message_type = 100）且 ntispam_custom_message_enabled = true 时才生效。
+ `p2p_option`	Object	可选	单聊消息功能配置项。
`check_friend`	Boolean	可选	该消息是否只发给好友（与消息发送者为好友关系的账号），默认为 false。若需要设置为好友关系才能发送消息，需先在网易云信控制台完成配置，再将该字段设置为 true。
+ `team_option`	Object	可选	高级群消息功能配置项。
`mark_as_read`	Boolean	可选	是否需要已读功能（仅对高级群消息有效），默认为 false（不需要）。
`ignore_chat_banned`	Boolean	可选	发送高级群消息时，是否忽略群禁言。默认为 false（不忽略）。若设置为 true（忽略），那么高级群内被禁言的情况下也可以发送消息。
`ignore_member_chat_banned`	Boolean	可选	发送高级群消息时，是否忽略成员禁言。默认为 false（不忽略）。如设置为 true（忽略），那么高级群内被禁言的用户也可以发送消息。
+ `superteam_option`	Object	可选	超大群消息功能配置项。
`ignore_chat_banned`	Boolean	可选	发送超大群消息时，是否忽略成员禁言。默认为 false（不忽略）。若设置为 true（忽略），那么超大群内被禁言的用户也可以发送消息。
`ignore_member_chat_banned`	Boolean	可选	发送超大群消息时，是否忽略成员禁言。默认为 false（不忽略）。如设置为 true（忽略），那么超大群内被禁言的用户也可以发送消息。
+ `robot_config`	Object	可选	机器人功能配置项。
`robot_account_id`	String	可选	机器人账号 ID，对应控制台提前设置好的机器人账号。仅在高级群中有效，其他会话类型中该字段无效。
`robot_topic`	String	可选	机器人消息话题，长度上限为 128 位字符。
`robot_function`	String	可选	机器人具体功能，长度上限为 128 位字符。
`robot_custom_content`	String	可选	机器人自定义内容，长度上限为 8192 位字符。
`ignore_member_chat_banned`	Boolean	可选	发送群消息时，是否忽略成员禁言。默认为 false（不忽略）。如设置为 true（忽略），那么群内被禁言的用户也可以发送群消息。
+ `ai_params`	Object	可选	数字人功能配置项。
`account`	String	必选	数字人账号 ID，对应控制台提前设置好的数字人账号。
`content`	Object	可选	发起给数字人的查询请求的内容，结构体为： { "msg": "xxx",//内容 "type": 0//类型，当前仅支持0表示文本 } 如果为空且消息为文本消息，则提取消息中的 `text` 字段。如果为空且不是文本消息，则返回 107336 错误。
`messages`	List<Object>	可选	数字人回溯的消息列表，结构体类似为： [ { "msg": "hello", "type": 0, "role": "user" }, { "msg": "hello, I am your AI assistant", "type": 0, "role": "assistant" } ]
`prompt_variables`	Object	可选	用于填充提示词中的变量，如果提示词中定义了变量，则该字段必填，结构体类似为： { "career"："厨师" }
`config`	Object	可选	模型相关的配置参数，不同模型配置类型不同。结构体类似为： {"maxTokens":1,"temperature":1,"prompt":"我是一个${{career}}，请回答我的问题：","topP":0.5}
`sender_no_sense`	Boolean	可选	发送方是否无感知，默认为 false。若设置为无感知（true），则消息发送者无该消息的多端、漫游、历史记录等信息。查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参考分页查询历史消息。发送者和接收者必须有一方感知，即不能将两者都设置为无感知。
`receiver_no_sense`	Boolean	可选	接收方是否无感知，默认为 false。若设置为无感知（true），则消息接收者无该消息的多端、漫游、历史记录等信息。查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参考分页查询历史消息。
`extension`	String	可选	开发者扩展字段，JSON 格式，长度上限为 1024 位字符。例如："{"k":"v"}"

请求体示例

json{
    "sender_no_sense": false,
    "receiver_no_sense": false,
    "extension": ""，
    "message": {
        "type": 0,
        "sub_type": 0,
        "text": "hahaha",
        "attachment": {
          "name":"图片发送于2015-05-07 13:59",
          "md5":"9894907e4ad9de4678091277509361f7",
          "url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e",
          "ext":"jpg",
          "w":6814,
          "h":2332,
          "size":388245
        }
    },
    "message_config": {
        "unread_enabled": true,
        "mutil_sync_enabled": true,
        "offline_enabled": true,
        "history_enabled": true,
        "roaming_enabled": true,
        "conversation_update_enabled": true
    },
    "route_config": {
        "route_enabled": true,
        "route_environment": ""
    },
    "push_config": {
        "push_enabled": false,
        "push_nick_enabled": false,
        "push_content": "",
        "push_payload": "",
        "push_forcepush_all": false,
        "push_forcepush_ids": [
            ""
        ],
        "push_forcepush_content": ""
    },
    "antispam_config": {
        "antispam_enabled": true,
        "antispam_business_id": "",
        "antispam_extension": "",
        "antispam_custom_message_enabled": false,
        "antispam_custom_message": "",
        "antispam_cheating": ""
    },
    "p2p_option": {
        "check_friend": false
    },
    "team_option": {
        "mark_as_read": false
    },
    "superteam_option": {
        "check_mute": false
    },
    "robot_config": {
        "robot_account_id": "qweqw",
        "robot_topic": "",
        "robot_function": "",
        "robot_custom_content": ""
    },
    "target_option": {
        "receiver_account_ids": ["accountId1"],
        "inclusive": true,
        "visible_to_new_member": false
    }
}

响应

Header

响应 Header 的参数说明请参考响应 Header。

响应体参数

参数名称	类型	说明	是否必返回
`code`	Integer	状态码，200 表示请求成功。	是
`msg`	String	提示信息。请求失败时返回错误信息，请求成功时返回 "success"。	是
+ `data`	Object	返回的 JSON 数据对象，请求失败则返回空对象。	是
`message_server_id`	Long	服务端消息 ID。	否
`sender_id`	String	消息发送方帐号 ID。	否
`conversation_type`	Integer	消息会话类型。	否
`receiver_id`	String	消息接收者账号 ID。	否
`create_time`	Long	消息发送时间戳。	否
`message_type`	Integer	消息类型。	是
`sub_type`	Integer	自定义消息子类型。	否
`text`	String	文本/提示消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。	否
`attachment`	Object	多媒体消息的属性或自定义消息内容。	否

响应体示例

json{
    "code": 200,
    "msg": "success",
    "data": {
        "message_type": 0,
        "text": "msg",
        "attachment": ["name", "image"],
        "sub_type": 1,
        "sender_id": "wqt",
        "conversation_type": 1,
        "receiver_id": "apiv2test"
    }
}

错误码

错误码	错误码描述	错误信息示例
200	请求成功	success
414	参数错误	parameter error
102404	用户不存在	account not exist
102421	用户被禁言	account chat banned
102422	用户被禁用	account banned
104404	好友不存在	friend not exist
107410	该 App 未开启发消息功能	messaging function disabled
107451	该消息未通过反垃圾审核	message hit antispam
107302	由于群成员过多导致标记已读失败，消息发送失败	sending message failed for marking message read failed for too many team members
107329	不是机器人帐号	%s is not chatbot account
107330	不允许发送方和接收方均无感知	sender or receiver must sense message
108311	超大群服务未开通	super team service disabled
108404	群不存在	team not exist
108302	非高级群	not advanced team
108423	群全体禁言	all team members chat banned
108306	群普通成员禁言	team normal member chat banned
109404	群成员不存在	team member not exist
109424	群成员被禁言	team member chat banned
107338	群定向消息不允许单向删除	One-way deletion is not allowed for target messages
107339	定向列表不能包含消息发送者	The message sender cannot be included in the receiver_account_ids
108318	群定向消息功能未开启	Targeting messages for group chat is disabled
108321	群消息定向成员可见时不支持新成员可见	Cannot allow targeted messages inclusive to new members
109318	强推列表包含非定向成员	The forced push list includes non-targeted accounts
107340	机器人消息不能是定向消息	robot can not send target message
108319	超大群消息不支持定向列表不可见	Setting 'inclusive' to false for super teams is not allowed
108320	超大群定向消息不支持新成员可见	Cannot make super team targeted messages visible to new members
500	服务器内部错误	internal server error

消息格式示例

文本消息(type = 0)

text 字段必填，attachment 字段无效。

{
  "msg":  "您好" //消息内容
}

图片消息(type = 1)

text 字段选填，attachment 字段必填。

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)

text 字段选填，attachment 字段必填。

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)

text 字段选填，attachment 字段必填。

json{
  "dur": 8003,
  "md5": "da2cef3e5663ee9c3547ef5d127f7e3e",
  "url": "http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412",
  "w": 360,
  "h": 480,
  "ext": "mp4",
  "size": 16420
}

地理位置消息(type = 4)

text 字段选填，attachment 字段必填。

json{
  "title": "中国浙江省杭州市网商路 599 号", // 地理位置 title
  "lng": 120.1908686708565, // 经度
  "lat": 30.18704515647036 // 纬度
}

文件消息(type = 6)

text 字段选填，attachment 字段必填。

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)

text 字段必填，attachment 字段无效。

json{
  "msg":  "您收到一份礼物"
}

自定义消息(type = 100)

text 字段选填，attachment 字段必填。

json//开发者自定义的 body，JSON 格式
{
  "myKey":myValue
}

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

功能描述
调用频率
请求
URL
Header
路径参数
请求体参数
请求体示例
响应
Header
响应体参数
响应体示例
错误码
消息格式示例
文本消息(type = 0)
图片消息(type = 1)
语音消息(type = 2)
视频消息(type = 3)
地理位置消息(type = 4)
文件消息(type = 6)
提示消息(type = 10)
自定义消息(type = 100)