微信发送文本消息接口详解（含@群成员）

前言

在企业自动化运营和客服系统场景中，通过程序精准控制微信发送文本消息是核心诉求之一。然而微信官方并未开放个人号的消息发送能力，开发者只能借助第三方协议接入方案来实现。本文以 WechatApi（个人微信HTTP API）为参考实现，系统讲解文本消息接口的调用原理、完整参数含义、@群成员的实现方式，以及常见的踩坑点和最佳实践，帮助开发者少走弯路。

一、为什么文本消息接口比你想的复杂

很多人第一次做微信消息推送，以为只要 POST 一个接口传个字符串就搞定了。实际上，光是"发一条文字消息"就涉及以下几个维度的决策：

1. 发送对象类型不同，参数体系不同

微信中存在三种典型的聊天对象：好友私聊、微信群、企业微信群。三者的标识符格式差异显著：

好友私聊：接收方是 wxid_xxxxxx 或绑定手机号推导出的 v3 格式 ID；
微信群：接收方是 xxxxxxxx@chatroom 格式；
公众号会话、服务号等场景则有额外的 openid 映射。

调用接口时必须把正确的 toId 填入请求体，否则消息发出后实际投递对象会出错，且接口本身不一定返回错误码（因为协议层只关心"发没发出去"，不校验对方是否真实存在于好友列表）。

2. @群成员需要同时传昵称和 wxid

这是最容易踩坑的地方。微信的 @ 功能并非纯文本拼接，它由两部分共同决定最终显示效果：

消息正文中嵌入 @昵称 占位文本（用户在气泡里看到的内容）；
独立的 mentionList 字段传入被@成员的 wxid 列表（协议层把消息推送给对应成员，并在其设备上触发"有人@我"提醒）。

如果只在文本里写了 @张三 而没有在 mentionList 里附上张三的 wxid，接收方在部分设备上不会收到@提醒，群内也不会高亮显示。两者缺一不可。

3. 设备 ID（appId）的绑定关系

WechatApi 采用 iPad 协议实现个人微信的接入，每个登录设备对应一个独立的 appId（也称 instanceId 或设备 ID）。发消息时必须在请求体中指定 appId，服务端才能路由到正确的微信账号实例进行发送。这一设计使平台可以同时管理多个账号，也是区别于传统 Web Hook 方案的关键架构差异。

二、接口鉴权机制说明

WechatApi 使用固定请求头进行 API 鉴权，格式简洁，适合后端服务直接调用：

httpPOST /api/v1/message/send-text HTTP/1.1
Host: api.wechatapi.net
Content-Type: application/json
VideosApi-token: YOUR_API_TOKEN

其中 VideosApi-token 是在控制台申请后分配的用户级凭证，和具体发送账号（appId）是分离的——一个 token 可以管理名下所有已登录设备。这种设计的好处是：做权限收敛时只需吊销 token，不会影响设备侧的登录状态。

关于 token 的安全实践：

不要把 token 硬编码进前端页面或 Git 仓库；
建议通过环境变量或密钥管理服务注入；
定期在控制台轮换 token，旧 token 立即失效。

三、发送普通文本消息：完整参数与示例

3.1 请求参数说明

字段名	类型	必填	说明
`appId`	string	是	登录设备 ID，从控制台获取
`toId`	string	是	接收方 wxid 或群 chatroom ID
`content`	string	是	消息正文，支持换行符 `\n`
`mentionList`	array	否	@成员的 wxid 列表，仅群聊有效
`mentionAll`	boolean	否	是否@所有人，`true` 时忽略 `mentionList`
`msgType`	integer	否	消息类型，文本固定传 `1`，默认也是 `1`

3.2 Python 调用示例

pythonimport requests

API_BASE = "https://api.wechatapi.net"   # 示意地址，非真实 endpoint
TOKEN = "your_api_token_here"
APP_ID = "your_app_id_here"

def send_text(to_id: str, content: str):
    url = f"{API_BASE}/api/v1/message/send-text"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": TOKEN,
    }
    payload = {
        "appId": APP_ID,
        "toId": to_id,
        "content": content,
        "msgType": 1,
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=10)
    return resp.json()

# 发给好友
result = send_text("wxid_abcdefgh123", "你好，这是一条来自系统的通知消息。")
print(result)

# 发给群聊
result = send_text("12345678@chatroom", "各位，今日例会15:00开始，请准时参加。")
print(result)

3.3 标准返回体结构

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "msgId": "7398271649012345678",
    "createTime": 1718000000
  }
}

ret 为 200 表示发送成功；
msgId 是消息的唯一标识，可用于后续消息撤回接口；
非 200 的常见错误码：401（token 无效）、403（appId 不属于当前 token）、429（触发频率限制）、500（微信侧异常）。

四、@群成员的实现原理与详细步骤

@功能是群场景下使用频率极高的能力，在客服机器人、群通知系统、微信群管理机器人等场景中几乎是标配。下面拆解完整实现路径。

4.1 第一步：获取群成员列表

在 @ 某人之前，必须先知道他的 wxid。群成员 wxid 可以通过"获取群成员"接口拉取：

bashcurl -X POST https://api.wechatapi.net/api/v1/group/member-list \
  -H "Content-Type: application/json" \
  -H "VideosApi-token: your_api_token_here" \
  -d '{
    "appId": "your_app_id_here",
    "groupId": "12345678@chatroom"
  }'

返回数据中每个成员对象包含 wxid（用于 mentionList）和 nickname（用于正文中的 @昵称 占位）。建议在业务层维护一张"群成员 wxid → 昵称"的本地缓存表，避免每次发消息都实时查询成员列表，减少 API 调用次数。

4.2 第二步：构造带@的消息请求

pythondef send_text_with_mention(group_id: str, content_template: str, mention_wxids: list, mention_nicknames: list):
    """
    content_template 示例: "@张三 @李四 明天的需求评审推迟到下午3点，请知悉。"
    mention_wxids: ["wxid_zhang3_xxx", "wxid_li4_xxx"]
    mention_nicknames: ["张三", "李四"]  # 仅用于拼接正文，顺序需与 wxids 对应
    """
    # 自动在消息开头拼接@文本（也可以由调用方自行构造）
    at_prefix = " ".join([f"@{nick}" for nick in mention_nicknames])
    full_content = f"{at_prefix} {content_template}".strip()

    url = "https://api.wechatapi.net/api/v1/message/send-text"
    headers = {
        "Content-Type": "application/json",
        "VideosApi-token": TOKEN,
    }
    payload = {
        "appId": APP_ID,
        "toId": group_id,
        "content": full_content,
        "mentionList": mention_wxids,
        "msgType": 1,
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=10)
    return resp.json()

# 使用示例
send_text_with_mention(
    group_id="12345678@chatroom",
    content_template="请在今天下班前提交周报，谢谢。",
    mention_wxids=["wxid_zhang3_xxx", "wxid_li4_xxx"],
    mention_nicknames=["张三", "李四"],
)

4.3 @所有人的特殊处理

当 mentionAll 设置为 true 时，接口会自动在消息中插入"@所有人"提醒，无需手动传 mentionList。但要注意：

群主或管理员账号才能成功触发@所有人的推送提醒；
普通群成员账号调用后，消息虽然发出，但部分群成员不会收到提醒；
高频使用@所有人可能触发微信风控，建议限制频率，每日不超过 2～3 次。

五、消息频率控制与风控规避

这是实际落地时最关键、也最容易被忽视的环节。微信对账号行为有一套智能风控体系，即便通过 iPad 协议接入，异常的消息行为同样会导致封号或功能受限。

5.1 合理的发送频率

场景	建议频率上限
单账号发送私聊	每分钟 ≤ 10 条
单账号发群消息	每分钟 ≤ 5 条
@所有人	每群每天 ≤ 3 次
批量群发（多群）	每次间隔 ≥ 3 秒，每日 ≤ 200 群

超出上述频率不一定立刻封号，但会积累风险分，当风险分超过阈值时微信会触发登录验证或直接限制发消息功能。

5.2 消息内容层面的注意事项

避免完全重复的消息：同样的文本内容连续发往多个对象，是典型的营销行为特征，触发风控概率极高。建议在模板中嵌入动态变量（对象昵称、时间戳、随机词语）制造差异。
不要在消息中嵌入裸 URL 链接：纯文本 URL 在微信中容易被识别为推广内容；如果需要附链接，建议走"发链接消息"接口（msgType=5），可以附带标题、描述和缩略图，用户体验更好且风险更低。
群消息中谨慎使用敏感关键词：微信对群聊内容有关键词过滤机制，涉及赌博、色情、诈骗等领域的内容即便通过 API 发出也会被拦截，情节严重会导致账号封禁。

5.3 账号"养号"策略

用于 API 接入的微信账号，建议在正式投入使用前进行至少 7～14 天的"养号"：

正常登录使用，添加 20+ 真实好友；
每天有正常的聊天记录（人工发几条）；
绑定实名信息和微信支付；
头像、昵称、个人简介填写完整。

经过养号的账号在协议层被判定为"正常用户"的概率更高，后续 API 调用时的风控门槛也会相应提升。

六、与其他消息类型的联合使用

文本消息只是 WechatApi 支持的消息类型之一。在构建完整的微信二次开发方案时，通常需要几种消息类型配合使用：

常见的多消息类型组合场景举例：

客服接待流程：用户发来咨询 → 机器人先发一条文本回复"您好，正在为您转接人工客服，请稍等" → 再发一张名片消息推送客服微信 → 最后发链接卡片附上知识库文章地址。

群运营通知：管理员触发任务 → 先发文本消息@相关成员点名 → 随后发图片消息附上活动海报 → 最后发链接消息引导进入报名页面。

SCRM 自动跟进：CRM 系统检测到客户进入某个阶段 → 触发 Webhook → 调用文本接口给对应销售人员的微信发提醒 → 销售人员点击消息内的链接直接跳转 CRM 详情页。

在微信 SCRM 场景下，文本消息接口还经常与"消息接收"回调结合，形成完整的双向通信链路——接收用户回复 → 解析意图 → 调用接口回复文本，这是构建智能客服机器人的基础架构。

七、常见问题与排查思路

Q1：接口返回 200 但对方没有收到消息？

首先确认 toId 格式是否正确（好友用 wxid，群聊必须带 @chatroom 后缀）。其次检查 appId 对应的账号是否还在线（可调用"获取登录状态"接口验证）。最后确认发送账号与接收对象是否存在好友关系——向非好友发私信，接口层面不报错，但消息实际上无法投递。

Q2：@群成员后对方没有收到@提醒？

检查两点：① mentionList 中传入的 wxid 是否准确（建议通过群成员列表接口实时获取，不要依赖缓存中的旧 wxid，部分用户换绑手机号后 wxid 会变）；② 正文中是否包含对应的 @昵称 文本，两者缺一不可。

Q3：发送成功但消息被撤回或不可见？

可能触发了微信内容审核。检查消息内容是否包含敏感词、外链 URL、或与历史违规内容相似的表述。建议先用普通账号手动发送同样内容测试是否正常显示，排除内容问题后再排查 API 层面。

Q4：频繁遇到 429 错误码？

说明触发了 WechatApi 平台的 API 频率限制。可以在业务层加入指数退避重试机制（首次等待 1 秒，第二次 2 秒，第三次 4 秒，最多重试 3 次），同时检查是否有并发请求导致短时间内请求量爆增。

小结

微信文本消息接口看似简单，实则涉及账号标识符体系、@成员的双字段机制、风控规避策略等多个技术细节。本文以 WechatApi 平台为参考，完整梳理了从鉴权、参数构造、@群成员实现到频率控制的全链路实践要点。

如果你正在构建企业微信客服系统、群运营机器人或 SCRM 自动化流程，WechatApi 基于 iPad 协议的稳定接入方案值得优先考虑——控制台注册地址：https://newmanager.wechatapi.net/dashboard/ ，接入文档：https://post.wechatapi.net 。掌握文本消息接口后，建议进一步了解链接消息、图片消息、名片消息等类型，把完整的消息能力串联成业务闭环。