微信邀请好友进群接口（含邀请确认）

前言

运营私域流量时，批量拉人进群是最高频的操作之一。然而微信客户端对邀请频率、人数上限都有严格限制，手动操作不仅费时费力，还极易触发风控。如何通过接口自动化实现"邀请好友进群"并处理好友需要确认的场景，是许多开发者和运营团队的核心诉求。本文结合 WechatApi 的实际调用方式，完整讲解这一流程的原理、参数和代码实现。

一、邀请进群的两种模式及触发条件

微信群的邀请逻辑并不是单一的，它会根据群人数和好友关系自动切换两种模式：

直接拉入（无需确认）：当群人数未满 40 人时，群主或群成员可以直接将好友拉入群聊，被邀请方无需主动点击确认，直接出现在群里。这种模式在接口层面只需要一次调用即可完成。

发送邀请链接（需要确认）：当群人数已达到或超过 40 人，微信会自动切换为"发送群邀请"模式——系统向被邀请的好友发送一条卡片消息，对方需要在聊天框中点击"接受邀请"才能入群。这种模式在接口层面涉及两步：先发出邀请，再监听或触发确认。

理解这两种模式的边界，是正确设计自动化流程的前提。很多开发者直接套用"拉人进群"接口，却发现对超过 40 人的群无效，根本原因就在于忽略了确认流程的存在。

WechatApi 基于 iPad 协议 深度还原了微信客户端的完整通信逻辑，两种模式都有对应的接口覆盖，且参数结构统一，便于业务层做统一封装。

二、接口调用鉴权与基础结构

在调用任何 WechatApi 接口之前，需要先了解统一的鉴权和请求规范。

鉴权方式：所有请求在 HTTP Header 中携带 VideosApi-token，值为你在控制台（https://newmanager.wechatapi.net/dashboard/）申请到的 API Token。

设备标识：每一个登录的微信实例对应一个 appId（设备 ID），业务参数中必须传入，用于区分多账号场景。

请求格式：统一为 HTTP POST，Content-Type: application/json，Body 为 JSON 对象。

返回格式：统一为 {"ret": 200, "msg": "操作说明", "data": {...}}，ret 为 200 表示成功，非 200 为各类错误码。

下面是一个最简单的鉴权请求示例，验证当前 token 和 appId 是否有效：

bashcurl -X POST https://api.example-wechatapi.net/v1/account/info \
  -H "Content-Type: application/json" \
  -H "VideosApi-token: YOUR_API_TOKEN_HERE" \
  -d '{
    "appId": "YOUR_APP_ID_HERE"
  }'

正常返回示例：

json{
  "ret": 200,
  "msg": "success",
  "data": {
    "wxid": "wxid_xxxxxxxx",
    "nickname": "测试账号",
    "status": 1
  }
}

如果 ret 返回 401，说明 token 无效或已过期；返回 403，说明 appId 与 token 不匹配。建议在业务代码中对这两个错误码做专门的异常处理，避免静默失败。

三、邀请好友进群接口（40 人以下直接拉入）

当群人数不足 40 人时，使用"直接邀请"接口即可将好友拉入群聊，无需对方二次确认。

核心参数说明见下表：

为什么单次不超过 5 个？ 微信服务端对单次批量邀请有隐性频率限制，一次性邀请过多会导致部分好友邀请失败，甚至触发账号风控。合理的做法是分批、分时调用，每批 3～5 人，批次间隔 5～15 秒。

Python 调用示例：

pythonimport requests
import time

API_TOKEN = "YOUR_API_TOKEN_HERE"
APP_ID = "YOUR_APP_ID_HERE"
BASE_URL = "https://api.example-wechatapi.net"

headers = {
    "Content-Type": "application/json",
    "VideosApi-token": API_TOKEN
}

def invite_to_chatroom(chatroom_id: str, member_wxids: list) -> dict:
    """
    直接邀请好友进群（适用于群人数 < 40 的场景）
    :param chatroom_id: 群 ID，如 "xxxxxxxx@chatroom"
    :param member_wxids: 好友 wxid 列表
    :return: 接口返回的 JSON 数据
    """
    url = f"{BASE_URL}/v1/chatroom/invite"
    payload = {
        "appId": APP_ID,
        "chatRoomId": chatroom_id,
        "memberList": member_wxids
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=15)
    result = resp.json()
    print(f"邀请结果: ret={result.get('ret')}, msg={result.get('msg')}")
    return result

# 分批邀请示例：将 20 个 wxid 分 4 批依次邀请
all_wxids = [f"wxid_user{i:04d}" for i in range(1, 21)]
batch_size = 5
chatroom_id = "xxxxxxxx@chatroom"

for i in range(0, len(all_wxids), batch_size):
    batch = all_wxids[i: i + batch_size]
    invite_to_chatroom(chatroom_id, batch)
    if i + batch_size < len(all_wxids):
        time.sleep(10)  # 批次间等待 10 秒，降低风控概率

成功返回示例：

json{
  "ret": 200,
  "msg": "邀请成功",
  "data": {
    "successList": ["wxid_user0001", "wxid_user0002"],
    "failList": []
  }
}

注意 data.failList 不为空时，需要针对失败的 wxid 做重试或排查（常见原因：对方已在群中、非好友关系、被对方拉黑等）。

四、发送群邀请（40 人以上，需对方确认）

当群人数达到 40 人及以上，必须改用"发送邀请链接"接口。该接口会向目标好友的私聊窗口发送一条群邀请卡片，对方点击"接受邀请"后才会真正加入群聊。

这个场景下，接口本身的调用方式与直接邀请类似，但有几个关键差异：

1. 接口端点不同：需要调用专门的"发送群邀请"接口，而非直接拉人的接口。
2. 无法强制入群：对方是否接受完全取决于本人操作，业务层需要设计等待和超时机制。
3. 可以监听入群事件：通过 WechatApi 的事件推送（Webhook 回调），可以实时接收"成员加入群聊"通知，从而判断邀请是否被接受。

pythondef send_chatroom_invitation(chatroom_id: str, invitee_wxid: str) -> dict:
    """
    向好友发送群邀请卡片（适用于群人数 >= 40 的场景）
    :param chatroom_id: 目标群 ID
    :param invitee_wxid: 被邀请好友的 wxid（单次只能发给一个人）
    :return: 接口返回结果
    """
    url = f"{BASE_URL}/v1/chatroom/sendInvitation"
    payload = {
        "appId": APP_ID,
        "chatRoomId": chatroom_id,
        "inviteeWxid": invitee_wxid
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=15)
    result = resp.json()
    print(f"发送邀请: wxid={invitee_wxid}, ret={result.get('ret')}, msg={result.get('msg')}")
    return result

重要提示：40 人以上的群邀请，每次只能针对一个好友发送邀请卡片，不支持批量传入 wxid 数组。这与直接拉人的接口有所不同，开发时需注意接口层的参数适配。

五、监听邀请确认事件（Webhook 回调处理）

"需要确认"的邀请场景下，业务系统如何知道对方已经接受了邀请？答案是通过 WechatApi 的 Webhook 事件回调机制。

在控制台配置好回调地址后，当群内有新成员加入时，WechatApi 会向你的服务推送一条 JSON 事件：

json{
  "type": "chatroom_member_join",
  "appId": "YOUR_APP_ID_HERE",
  "data": {
    "chatroomId": "xxxxxxxx@chatroom",
    "memberWxid": "wxid_user0001",
    "inviterWxid": "wxid_your_account",
    "joinTime": 1718000000,
    "joinType": 2
  }
}

其中 joinType 字段区分了入群方式：

通过判断 joinType == 2 且 inviterWxid 为自己的账号，即可精确识别"通过邀请确认入群"的事件，进而触发业务逻辑（如记录入群时间、发送欢迎语、更新 CRM 数据等）。

这种事件驱动的设计，相比轮询接口查询群成员列表要高效得多，也是 微信群管理机器人 和 微信 SCRM 系统 的标准实现方案。

六、常见错误码与排查指南

在实际接入过程中，以下几类错误最为常见，整理如下供快速定位：

其中 610 错误 尤其值得关注——这正是系统提示"当前群超过 40 人，需切换模式"的信号。建议在业务代码中对 610 做自动路由：捕获该错误码后，自动调用"发送邀请链接"接口重试，实现两种模式的无缝切换。

pythondef smart_invite(chatroom_id: str, wxid: str) -> dict:
    """
    智能邀请：自动根据返回码切换直接拉入或发送邀请卡片"""
    result = invite_to_chatroom(chatroom_id, [wxid])
    if result.get("ret") == 610:
        print(f"群人数超限，切换为发送邀请链接模式: {wxid}")
        result = send_chatroom_invitation(chatroom_id, wxid)
    return result

这种自适应逻辑在生产环境中非常实用，尤其是群规模动态变化的运营场景。

七、风控合规与最佳实践

私域运营中，账号安全是重中之重。以下几点是使用群邀请接口时必须遵守的操作规范：

控制邀请频率：单个账号每日邀请总人数建议不超过 50 人，单次批量不超过 5 人，批次间隔不低于 10 秒。频繁的群邀请操作是微信风控的重点监测项。

只邀请真实好友：群邀请接口要求被邀请方必须是当前账号的微信好友，不能邀请陌生人。这不仅是接口层的技术限制，也是微信平台的合规要求。

账号预热：新登录的账号不建议立刻大量调用群邀请接口，应先正常使用一段时间（发消息、收消息），让账号行为模式趋于自然。

多账号分散操作：如果需要大规模运营，建议将任务分配到多个账号，而不是集中在单一账号上高频操作。WechatApi 的多 appId 架构天然支持多账号并发管理。

异常登录态检测：定期调用账号状态查询接口，及时发现登录态失效（错误码 601），避免因账号掉线导致邀请任务静默失败。

以上这些实践，在 个人微信 API 的使用文档和 微信二次开发 场景中都有详细说明，建议在接入前系统阅读。

小结

微信邀请好友进群看似简单，实则涉及两种不同的交互模式（直接拉入 vs 发送邀请确认），且需要结合 Webhook 事件回调才能完整闭环。WechatApi 基于 iPad 协议提供了完整覆盖这两种模式的接口，配合统一的鉴权体系（VideosApi-token + appId）和标准化的返回结构，可以大幅降低接入成本。

核心要点总结：群人数 < 40 人用直接邀请接口，≥ 40 人用发送邀请链接接口；通过 Webhook 监听 chatroom_member_join 事件判断是否接受邀请；业务层做好频率控制和错误码自适应路由，是保障账号安全的关键。

如需了解更多接口细节，可前往开发文档 https://post.wechatapi.net 查阅，或在控制台 https://newmanager.wechatapi.net/dashboard/ 申请试用。