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

功能描述

• 各类消息及相关功能的更多介绍，请参考 消息概述。

• 该接口可以在会话中发送一条单聊/群聊消息。会话类型包括单聊、群聊、超大群会话。聊天室消息发送请参考 发送聊天室消息。

• 自 10.4.0 起，支持发送群定向消息。即发送群消息时，可以指定接收消息的群成员列表。为避免异步操作失败，同时支持关闭检查群成员身份。

调用频率

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

请求信息

请求 URL

POST https://{endpoint}/im/v2/conversations/{conversation_id}/messages

请求 URL 中的 {endpoint} 代表服务地址域名，您可以根据用户服务区域选择中国大陆和海外服务地址，并支持搭建高可用主备域名机制。详情请参考 调用方式 服务地址章节。

请求头参数

请求 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	否	非文本消息/提示消息的属性或自定义消息内容。 对于非文本消息/提示消息，该字段必填，每种消息的属性参数见：消息格式示例。 该字段长度上限以使用的 IM 套餐为准。IM 旗舰版及以上套餐才支持配置字段上限。
message_client_id	String	否	客户端消息 ID。若不传入，则会自动生成。
- 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。
check_team_member_valid	Boolean	否	发送群定向消息时，是否需要验证定向成员的群成员身份。默认为 true，即需要验证群成员身份。
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 推送或安卓系统通知栏推送，默认为 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 位字符。参数值设置请参考网易易盾的反垃圾增强版用户 场景扩展参数。antispam_extension 传入的值，默认覆盖本接口的 extension 参数设置。反作弊相关的 email、phone、token、extension，请抄送到 antispam_cheating 字段中。其他用户增值信息，请抄送到 antispam_extension 字段。
antispam_cheating	String	否	透传给网易易盾的反作弊文本检测参数，格式为 JSON，长度限制 1024 位字符。参数值设置请参考网易易盾的反垃圾防刷版 专属参数。
antispam_custom_message_enabled	Boolean	否	是否对自定义消息的指定内容（antispam_custom_message）进行审核。 若已在 网易云信控制台 开通安全通，该字段默认为 false（不过审核），若需要设置该条自定义消息经过审核，则设置为 true。 若未开通安全通，该字段无效。
antispam_custom_message	String	否	自定义的安全通检测内容, JSON 格式，长度限制同 text 字段。格式如下： {"type":1,"data":"custom content"} 字段说明： type: 1 为文本。2 为图片。3 为视频。4 为音频。5 为图文。 data: type 为 1、2、3、4 时，data 为字符串，分别传入文本内容、图片地址、视频/音频地址。 type 为 5 时，data 为 JSON 格式，例如： { "text":""，//1 个文本 必填 "images":["url1,"url2"], //最大 6 个图片 必填 "textbid":"", //文本检测业务 ID 选填 "picbid":"" //图片检测业务 ID 选填 } 该参数只对自定义消息（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（忽略），那么高级群内被禁言的用户也可以发送消息。
check_team_member_valid	Boolean	否	发送高级群消息时，是否需要验证群成员身份，默认为 true（需要）。如设置为 false（不需要），那么不会验证群成员身份。
- superteam_option	Object	否	超大群消息功能配置项。
ignore_chat_banned	Boolean	否	发送超大群消息时，是否忽略成员禁言。默认为 false（不忽略）。若设置为 true（忽略），那么超大群内被禁言的用户也可以发送消息。
ignore_member_chat_banned	Boolean	否	发送超大群消息时，是否忽略成员禁言。默认为 false（不忽略）。如设置为 true（忽略），那么超大群内被禁言的用户也可以发送消息。
check_team_member_valid	Boolean	否	发送超大群消息时，是否需要验证群成员身份，默认为 true（需要）。如设置为 false（不需要），那么不会验证群成员身份。
- robot_config	Object	否	机器人功能配置项。
robot_account_id	String	否	机器人账号 ID，对应控制台提前设置好的机器人账号。仅在高级群中有效，其他会话类型中该字段无效。
robot_topic	String	否	机器人消息话题，长度上限为 128 位字符。
robot_function	String	否	机器人具体功能，长度上限为 128 位字符。
robot_custom_content	String	否	机器人自定义内容，长度上限为 8192 位字符。
- 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"："chef" }
config	Object	否	模型相关的配置参数，不同模型配置类型不同。结构体类似为： {"maxTokens":1,"temperature":1,"prompt":"我是一个${{career}}，请回答我的问题：","topP":0.5}
- thread_config	Object	否	Thread 消息配置项。该功能需要单独开通。
- thread_root	Object	否	Thread 根消息对象。
sender_id	String	否	根消息的发送者。
receiver_id	String	否	根消息的接收者。
create_time	Long	否	根消息的发送时间。
message_server_id	Long	否	根消息的服务器消息 ID。
message_client_id	String	否	根消息的客户端消息 ID。
- thread_reply	Object	否	被回复的消息对象。
sender_id	String	否	被回复消息的发送者。
receiver_id	String	否	被回复消息的接收者。
create_time	Long	否	被回复消息的发送时间。
message_server_id	Long	否	被回复的根消息的服务器消息 ID。
message_client_id	String	否	被回复消息的客户端消息 ID。
sender_no_sense	Boolean	否	发送方是否无感知，默认为 false。若设置为无感知（true），则消息发送者无该消息的多端、漫游、历史记录等信息。 查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参考 分页查询历史消息。发送者和接收者必须有一方感知，即不能将两者都设置为无感知。
receiver_no_sense	Boolean	否	接收方是否无感知，默认为 false。若设置为无感知（true），则消息接收者无该消息的多端、漫游、历史记录等信息。 查询历史消息时可设置是否在历史记录查询结果中包含无感知消息，具体参考 分页查询历史消息。
extension	String	否	开发者扩展字段，JSON 格式。例如："{\"k\":\"v\"}" 该字段长度上限以使用的 IM 套餐为准。IM 旗舰版及以上套餐才支持配置字段上限。如果您设置了 antispam_extension，则 extension 会被覆盖。

请求体示例

JSON{
    "sender_no_sense": false,
    "receiver_no_sense": false,
    "extension": "",
    "message": {
        "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
    },
    "target_option": {
        "receiver_account_ids": ["accountId1"],
        "inclusive": true,
        "visible_to_new_member": false
    },
    "thread_config": {
        "thread_root": {
            "sender_id": "xx",
            "receiver_id": "xx",
            "create_time": 123,
            "message_server_id": 123,
            "message_client_id": "xx"
        },
        "thread_reply": {
            "sender_id": "xx",
            "receiver_id": "xx",
            "create_time": 123,
            "message_server_id": 123,
            "message_client_id": "xx"
        }
    }
}

响应信息

响应头参数

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

响应体参数

参数名称	类型	说明	是否必返回
code	Integer	状态码，200 表示请求成功。	是
msg	String	提示信息。请求失败时返回错误信息，请求成功时返回 "success"。	是
- data	Object	返回的 JSON 数据对象，请求失败则返回空对象。	是
message_server_id	Long	服务端消息 ID。	否
message_client_id	String	客户端消息 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	多媒体消息的属性或自定义消息内容。	否
- thread_config	Object	Thread 消息配置项。	否
- thread_root	Object	Thread 根消息对象。	否
sender_id	String	根消息的发送者。	否
receiver_id	String	根消息的接收者。	否
create_time	Long	根消息的发送时间。	否
message_server_id	Long	根消息的服务器消息 ID。	否
message_client_id	String	根消息的客户端消息 ID。	否
- thread_reply	Object	被回复的消息对象。	否
sender_id	String	被回复消息的发送者。	否
receiver_id	String	被回复消息的接收者。	否
create_time	Long	被回复消息的发送时间。	否
message_server_id	Long	被回复消息的服务器消息 ID。	否
message_client_id	String	被回复消息的客户端消息 ID。	否

响应体示例

JSON{
    "code": 200,
    "msg": "success",
    "data": {
        "message_type": 0,
        "message_client_id": "clientid",
        "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 字段无效。

JSON{
  "msg": "Hi" //消息内容
}

图片(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": "You received a present."
}

自定义(type = 100)

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

JSON//您自定义的 body，JSON 格式
{
  "myKey":myValue
}