用接口在企微群聊里 @ 某个人，走的是富文本消息接口，不是普通文本接口。这篇讲清楚 sendRichText 的片段模型：一段消息由文本、表情、@ 混合拼成，@ 谁用 userId 控制，@ 全员有单独的写法。

背景痛点

很多人用发文本接口能跑通，就默认 @ 功能也是填个字符串，比如在内容里写一个 @张三，结果对方手机上只显示纯文本，没有任何提醒效果。群聊 @ 是一种结构化能力，必须用富文本接口的片段来表达，这一点不看文档很难猜对。

原理

富文本消息把 content 设计成一个数组，每一项是一个片段，用 type 区分：type 0 是纯文本，type 3 是表情，type 5 是 @。发送时按数组顺序拼成一条消息。

@ 的控制方式在 type 5 上分叉：片段带 userId 就是 @ 这个人，不带 userId 就是 @ 所有人。userId 是对方在会话里的身份 ID，从消息推送或群资料里能拿到。

核心实现

一条"通知 + @ 负责人"的群消息，请求体大致长这样（示例代码，需按官方文档校验，字段名以接口页为准）：

payload = {
    # 示例代码，需按官方文档校验
    "appid": APPID,
    "conversationId": room_id,          # 群聊填 roomId
    "content": [
        {"type": 0, "text": "今晚 21:00 系统升级，"},
        {"type": 5, "userId": 7881300000000002},   # @ 指定成员，int64
        {"type": 0, "text": " 负责确认回滚预案。"},
    ],
}
resp = requests.post(f"{BASE_URL}/wx-api/api/message/sendRichText",
                     headers={"Authorization": f"Bearer {CREDENTIAL}"},
                     json=payload, timeout=10).json()

想 @ 全员，把 type 5 那个片段的 userId 去掉即可。表情用 type 3，内容是形如 [愉快] 的表情码，和文本片段穿插使用。

踩坑

一、sendText 的 content 是字符串或 {type, text} 数组的简化形态，而 sendRichText 的 content 必须是片段数组。两个接口不能混着填，@ 片段放进 sendText 不会生效。

二、userId 是 int64 大整数，19 位的 ID 在 JavaScript 里直接用 Number 解析会失真，@ 错人都不带报错的。Node 服务解析群资料时要用大整数安全的解析方式。

三、发送成功后，返回的 data.content 就是刚才那组片段，可以拿来核对 @ 对象是否正确；@ 的提醒效果要看客户端，接口返回成功不等于对方手机震动了。

四、表情码依赖账号支持的表情集合，生僻表情码可能渲染不出来，正式环境里先挑常用表情试。

总结

群聊 @ 的实现路径就三步：拿群 roomId、按片段数组组织 content、调 sendRichText。这套片段模型是企微消息体系里少有的结构化设计，理解一次到处能用。示例基于 Eyun 平台的企微接口整理，片段 type 的完整取值和返回结构，以官方开发文档的消息模块为准。