群里拼一句 @张三 看下工单，气泡上有字，张三没有强提醒。手工发的时候客户端会弹出选人。走接口时，很多人只改了正文，没改「提到谁」。展示名和提醒对象不是同一个字段。外部群更不能拿官方内部群机器人那套 @ 语法来套。

重名、改名、群名片和通讯录不一致，都会把提醒打到别人身上。主键只能是成员的 userId。

正文负责看见，名单负责提醒

文本接口的 content 决定会话里出现什么字。能不能在对方会话里形成可点的提醒，取决于发送方法有没有带被提醒成员。字段名以文档为准，不要自己发明一个和内部群 Webhook 一样的 @userid 就当过了。内部群机器人和员工身份发言，执行主体不同，@ 行为不能互相当验收。

取 userId 不要靠昵称搜索。从该群成员列表读，或从对方在本群发言的回调里记下。记下来的是 ID，展示名只做快照。快照用来写 content 里的 @张三，让人眼对得上。提醒列表里必须是 ID。只写字、不传人，就是「有 @ 无提醒」。只传人、字对不上，有人会收到提醒却看不懂在叫谁。

先保证群文本能到，再叠加提醒。群文本仍用 roomId：

def build_group_text(guid, room_id, nickname, user_id, text):
    # user_id 必须来自成员列表或回调，不能来自昵称搜索
    content = f"@{nickname} {text}"
    body = {
        "method": "/msg/sendText",
        "params": {
            "guid": guid,
            "toId": room_id,
            "content": content,
        },
    }
    # 被提醒人如何随接口传递，以文档为准；这里只强调不要用昵称当主键
    return body, {"mention_user_id": user_id, "session_type": "room"}

本地把 mention_user_id 和这次调用绑在审计里。文档若要求额外参数，审计字段应和实际请求一起落。缺了人还报成功，验收不能过。

全员提醒不是指定提醒的替代

群发通知偷懒写成全员，等于每次状态变更都震所有人。指定工单负责人应用指定成员。全员和指定是两种产品能力，开关要分开。员工已不在群，任何 @ 都不应再打；任务停在对象失效。

验收：只改 content 含 @昵称、不传成员 ID，被叫的人不应出现强提醒；补上文档要求的成员参数后，被叫人有提醒且点开是这句；把 ID 换成群里另一个人，提醒应跟着 ID 走，不跟昵称走。改群名片后再测一次，防止有人把名片写进主键。

查看企业微信 API 文档：
https://doc.qiweapi.com/