网易云信服务端支持对七天内已发送成功的消息进行二次编辑，从而更新消息。

对于同一个消息（以消息 ID 为准），1s 内不能更新多次，否则会报 107449 错误。

调用频率

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

请求信息

请求 URL

POST https://{endpoint}/im/v2/messages/actions/modifyMsg

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

请求头参数

请求 Header 的参数说明，请参考 调用方式。

请求体参数

参数名称	类型	是否必选	描述
operator	String	是	更新（二次编辑）消息的操作者用户账号 ID。更新消息的操作者需要权限，默认只有消息发送者和群主才有更新消息权限。
extension	String	否	开发者扩展字段，JSON 格式。例如："{"k":"v"}"。 该字段长度上限以使用的 IM 套餐为准。IM 旗舰版及以上套餐才支持配置字段上限。
type	Integer	是	待更新消息的原始会话类型。 1：单聊。 2：高级群。 3：超大群。 该参数设置必须和原始消息保持一致。
- message	Object	是	消息体。
message_server_id	Long	是	待更新消息的原始 ID。该参数设置必须和原始消息保持一致。
receiver_id	String	是	待更新消息的原始接收者 ID 或群组 ID。该参数设置必须和原始消息保持一致。
time	Long	是	待更新消息的原始发送时间，默认只能修改七天内已发送的消息。该参数设置必须和原始消息保持一致。
sender_id	String	是	待更新消息的原始发送者。该参数设置必须和原始消息保持一致。
message_type	Integer	是	待更新消息的原始消息类型。 0：文本消息 1：图片消息 2：语音消息 3：视频消息 4：地理位置消息 6：文件消息 10：提示消息 100：自定义消息 请求参数中的 message_type 取不同值时，涉及到的可修改参数请参考 消息更新范围。 对于未开通安全通功能的应用，自定义消息不会进行内容审核。 该参数设置必须和原始消息保持一致。
sub_type	Integer	否	自定义消息子类型，大于 0。message_type = 100 时该字段才有效。
text	String	否	对于文本消息和提示消息，值为消息内容，长度上限 5000 位字符。 对于非文本/提示消息，该字段非必填，值为描述信息，可用于 全文关键字搜索历史消息，长度上限 500 位字符。
attachment	Object	否	非文本消息/提示消息的属性或自定义消息内容。 对于非文本消息/提示消息，每种消息的属性参数，请参考 消息格式示例。 该字段长度上限以使用的 IM 套餐为准。IM 旗舰版及以上套餐才支持配置字段上限。
- message_config	Object	否	消息配置项。
conversation_update_enabled	Boolean	否	是否将该消息更新至会话列表服务中本会话的最后一条消息。默认为 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，最终推送文案为：默认文案 其中，根据消息类型，默认文案分为以下几种： 文本消息默认文案：更新了一条消息 地理位置默认文案：更新了一个地理位置 语音消息默认文案：更新了一段语音 视频消息默认文案：更新了一段视频 文件消息默认文案：更新了一个文件 图片消息默认文案：更新了一张图片 Tip 消息默认文案：更新了一条提醒 语音聊天邀请消息默认文案：您收到一条消息更新 视频聊天邀请消息默认文案：您收到一条消息更新
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 为图片；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	否	高级群消息功能配置项。
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（不需要），那么不会验证群成员身份。

消息更新范围

• 原始消息属性参数

  因更新消息是在原始消息的基础上进行修改，因此，前文请求体参数表格中的标红参数必须与一条原始消息一一对应，请勿设置为随意的其他取值。

• message_type

  请求参数中的 message_type 取不同值时，涉及到的可修改参数如下表所示。例如，当 message_type 取值为 1（图片消息）时，您在更新消息时，能够同步修改的消息范围为 sub_type、text、extension。

  message_type 取值	sub_type	text	attachment	extension
  -	自定义消息子类型。	消息内容。	非文本消息/提示消息的属性或自定义消息内容。	JSON 格式的开发者扩展字段。
  0：文本消息	✔️️	✔️️	-	✔️️
  1：图片消息	✔️️	✔️️	-	✔️️
  2：语音消息	✔️️	✔️️	-	✔️️
  3：视频消息	✔️️	✔️️	-	✔️️
  4：地理位置消息	✔️️	✔️️	✔️️	✔️️
  6：文件消息	✔️️	✔️️	-	✔️️
  10：提示消息	✔️️	✔️️	-	✔️️
  100：自定义消息	✔️️	✔️️	✔️️	✔️️

请求体示例

JSON{
    "operator": "zhangsan",
    "type": 1,
    "extension": ""，
    "message": {
        "message_server_id": 9899821270208,
        "receiver_id": "apiv2test",
        "time":1707035841692,
        "sender_id": "yx",
        "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": {
        "conversation_update_enabled": true
    },
    "route_config": {
        "route_enabled": true,
        "route_environment": ""
    },
    "push_config": {
        "push_enabled": false,
        "push_nick_enabled": false,
        "push_content": "",
        "push_payload": ""
    },
    "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": {
        "ignore_chat_banned": false
    },
    "superteam_option": {
        "ignore_chat_banned": false
    }
}

响应信息

响应头参数

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

响应体参数

参数名称	类型	说明	是否必返回
code	Integer	状态码，200 表示请求成功。	是
msg	String	提示信息。请求失败时返回错误信息，请求成功时返回 "success"。	是
- data	Object	返回的 JSON 数据对象，请求失败则返回空对象。	是
modify_account_id	String	消息更新者的用户账号 ID。 只有消息被更新才会返回该字段。	否
modify_time	Long	消息的更新时间。 只有消息被更新才会返回该字段。	否
message_server_id	Long	服务端消息 ID。	是
sender_id	String	消息发送方账号 ID。	是
receiver_id	String	消息接收者账号 ID。	否
create_time	Long	消息发送时间戳。	是
message_type	Integer	消息类型。0：文本消息；1：图片消息；2：语音消息；3：视频消息；4：地理位置消息；6：文件消息；10：提示消息；100：自定义消息。	是
sub_type	Integer	自定义消息子类型。	否
text	String	文本/提示消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。	否
attachment	Object	多媒体消息的属性或自定义消息内容。	否
extension	String	消息扩展字段。	否

响应体示例

JSON{
  "code": 200,
  "msg": "success",
  "data": {
    "extension": "更新消息扩展字段2025-07-21T16:34:22",
    "create_time": 1753086857386,
    "sub_type": 0,
    "receiver_id": "test",
    "modify_time": 1753086862623,
    "message_server_id": 14983048303189,
    "modify_account_id": "test1",
    "message_type": 0,
    "text": "更新消息内容2025-07-21T16:34:22",
    "sender_id": "test1"
  }
}

错误码

本文仅列举部分业务接口错误码，完整列表请参考客户端 API 错误码。

错误码	错误码描述	错误信息示例
200	请求成功	success
414	参数错误	parameter error
102404	用户不存在	account not exist
104404	好友不存在	friend not exist
107341	更新消息功能未开通	modify msg function disabled
107342	该消息类型不允许更新	modify msg type disabled
107343	该消息参数不允许更新	modify msg param disabled
107344	不允许更新消息	not allowed to modify messages
107404	消息不存在	message not exist
107451	消息命中反垃圾	message hit antispam
108423	群被禁言	all team members chat banned
108306	群普通成员禁言	team normal member chat banned
109424	群成员被禁言	account muted in the team
108311	超大群服务未开通	super team service disabled
107410	App 发消息功能未开启	messaging function disabled
107449	操作频繁，请重试	try again
109318	强推列表中包含非定向成员	The forced push list includes non-targeted accounts
500	服务器内部错误	internal server error