跳转到主要内容

WhatsApp Groups API：创建、管理和删除群组

摘要

使用 WhatsApp Groups API 以编程方式创建和管理 WhatsApp 群组。您可以创建群组、向待处理的联系人发送邀请、移除参与者、删除群组以及检索活跃群组列表。

注意：WhatsApp Groups API 适用于 Business 计划。

说明

开始之前

在使用 WhatsApp Groups API 之前：

  • 请确保您的 Wati 账户处于 Business 计划。

  • 生成 Wati API 令牌并妥善保管。

  • 使用 Wati API 文档中提供的 API 基础 URL。

有关更多信息，请参阅 身份验证。Wati API 使用 Bearer Token 身份验证，请求必须在 Authorization 标头中包含 API 令牌。

身份验证

在 API 请求中包含以下标头：

Authorization: Bearer <your_api_token>
Content-Type: application/json

例如：

curl --location 'https://live-mt-server.wati.io/xxxxxx/api/ext/v3/conversations/groups' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'Content-Type: application/json'

注意：请使用您 Wati 账户中显示的 API 基础 URL（Connectors > API Docs > API Endpoint），而不是上面的示例 URL。

安全性：切勿共享您的 API 令牌或将其提交到公共代码库。Wati 建议将 API 凭据存储在环境变量或密钥管理器中。

可用端点

方法

端点

描述

POST

/api/ext/v3/conversations/groups

创建一个 WhatsApp 群组

DELETE

/api/ext/v3/conversations/groups/{groupId}

删除一个 WhatsApp 群组

POST

/api/ext/v3/conversations/groups/{groupId}/invites

向待处理联系人发送邀请

DELETE

/api/ext/v3/conversations/groups/{groupId}/participants

从群组中移除参与者

POST

/api/ext/v3/conversations/groups/list

列出活跃的 WhatsApp 群组

1. 创建一个 WhatsApp 群组

POST /api/ext/v3/conversations/groups

创建一个新的 WhatsApp 群组。

您可以选择指定一个渠道。如果不指定，则使用默认渠道。客服由电子邮件地址识别，而联系人由电话号码或受支持的联系人目标识别。

请求主体

{
  "channel": "MyChannel",
  "name": "VIP Support Group",
  "description": "Group for VIP customers",
  "owner_email": "[email protected]",
  "operator_emails": [
    "[email protected]"
  ],
  "contact_targets": [
    "14155551234",
    "14155555678"
  ],
  "join_approval_mode": "auto_approve"
}

请求主体参数

字段

类型

描述

channel

string

要使用的渠道。如果省略，将使用默认渠道。

name

string

WhatsApp 群组的名称。

description

string

WhatsApp 群组的描述。

owner_email

string

群组所有者的电子邮件地址。

operator_emails

array

要添加到群组的客服的电子邮件地址。

contact_targets

array

要添加到群组的联系人的电话号码、BSUID 或 ContactId。每个群组最多 7 个联系人。

join_approval_mode

string

指定群组加入审批模式。

响应

请求成功时返回 201 Created 以及新创建群组的详细信息。

{
  "group": {
    "id": "6828abc123def456789012ab",
    "name": "VIP Support Group",
    "description": "Group for VIP customers",
    "invite_link": "",
    "channel_id": "ch_123",
    "conversation_id": "conv_456",
    "operators": [
      {
        "id": "682800000000000000000001",
        "operator_id": "op_id",
        "name": "Owner Name",
        "role": "owner",
        "added_at": "2026-08-13T08:27:00.8447035Z"
      }
    ],
    "contacts": [
      {
        "id": "682800000000000000000003",
        "contact_id": "contact_id",
        "wa_id": "+14155551234",
        "name": "Contact Name",
        "join_status": "pending"
      }
    ],
    "created_at": "2026-08-13T08:27:00.8448051Z"
  }
}

响应代码

代码

描述

201

群组已成功创建。

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

2. 删除一个 WhatsApp 群组

DELETE /api/ext/v3/conversations/groups/{groupId}

删除指定的 WhatsApp 群组。

如果群组已被删除，端点仍会返回 200 OK。

路径参数

参数

类型

必须

描述

groupId

string

是

要删除的群组 ID。

响应

请求成功时返回 200 OK。

{
  "result": true
}

响应代码

代码

描述

200

群组已成功删除。

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

3. 发送群组邀请

POST /api/ext/v3/conversations/groups/{groupId}/invites

向所有状态仍为“待处理”的联系人发送群组邀请。

API 会检查群组中的联系人，识别出加入状态为“待处理”的联系人，并将群组邀请模板发送到每个联系人的 1:1 对话中。

路径参数

参数

类型

必须

描述

groupId

string

是

要发送邀请的群组 ID。

响应

请求成功时，将返回每个待处理联系人的邀请结果。

{
  "total_pending": 3,
  "sent": 2,
  "failed": 1,
  "results": [
    {
      "contact_name": "Alice",
      "phone": "14155551234",
      "success": true
    },
    {
      "contact_name": "Bob",
      "phone": "14155555678",
      "success": true
    },
    {
      "contact_name": "Charlie",
      "phone": "",
      "success": false,
      "error": "BSUID-only contact, no phone number"
    }
  ]
}

响应包括：

  • total_pending：加入状态为待处理的联系人数量。

  • sent：成功发送的邀请数量。

  • failed：未能发送的邀请数量。

  • results：每个待处理联系人的邀请结果。

响应代码

代码

描述

200

邀请结果已成功返回。

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

4. 从 WhatsApp 群组中移除参与者

DELETE /api/ext/v3/conversations/groups/{groupId}/participants

从 WhatsApp 群组中移除客服和/或联系人。

您必须至少提供一个客服电子邮件或联系人目标。

路径参数

参数

类型

必须

描述

groupId

string

是

要从中移除参与者的群组 ID。

请求主体

{
  "operator_emails": [
    "[email protected]"
  ],
  "contact_targets": [
    "14155551234"
  ]
}

请求主体参数

字段

类型

描述

operator_emails

array

要从群组中移除的客服的电子邮件地址。

contact_targets

array

要从群组中移除的联系人的电话号码、BSUID 或 ContactId。每个群组最多 7 个联系人。

您可以提供 operator_emails、contact_targets 或两者同时提供。必须至少提供其中之一。

响应

请求成功时返回 200 OK。

{
  "result": true
}

响应代码

代码

描述

200

参与者已成功移除。

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

5. 列出活跃的 WhatsApp 群组

POST /api/ext/v3/conversations/groups/list

返回游标分页的活跃 WhatsApp 群组列表。

您可以选择按渠道或特定群组 ID 过滤结果。如果不指定，则使用默认渠道。

请求主体

{
  "channel": "MyChannel",
  "limit": 20
}

请求主体参数

字段

类型

描述

channel

string

要使用的渠道。如果省略，将使用默认渠道。

limit

integer

响应中返回的群组数量。

响应

请求成功时返回 200 OK 以及活跃群组和分页信息。

{
  "groups": [
    {
      "id": "6828abc123def456789012ab",
      "name": "VIP Support Group",
      "description": "Group for VIP customers",
      "invite_link": "https://chat.whatsapp.com/abc123",
      "channel_id": "ch_123",
      "conversation_id": "conv_456",
      "operators": [
        {
          "id": "682800000000000000000001",
          "operator_id": "op_id",
          "name": "Owner",
          "role": "owner",
          "added_at": "2026-08-13T08:27:00.8595387Z"
        }
      ],
      "contacts": [
        {
          "id": "682800000000000000000003",
          "contact_id": "contact_id",
          "wa_id": "+14155551234",
          "name": "Alice",
          "join_status": "joined",
          "joined_at": "2026-08-13T08:27:00.8595402Z"
        }
      ],
      "created_at": "2026-08-13T08:27:00.8595404Z"
    }
  ],
  "continuous_token": "eyJsIjoiNjgyOGFiYzEyM2RlZjQ1Njc4OTAxMmFiIn0=",
  "total": 5
}

分页

List Groups 端点以分页方式返回结果。

如果有更多群组，响应将包含一个 continuous_token。使用此令牌可检索后续页面。

当 continuous_token 为空或 null 时，表示没有更多结果。

响应代码

代码

描述

200

活跃群组列表已成功返回。

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

错误响应

WhatsApp Groups API 端点可能会返回以下 HTTP 状态代码：

代码

描述

400

请求无效。

401

请求未经授权。

403

请求被禁止。

429

请求过多。

500

发生了意外错误。

对于 400、403 和 500 响应，API 可能会返回其他详细信息，例如错误代码、消息和时间戳。

错误响应示例

{
  "details": "string",
  "code": 0,
  "message": "string",
  "timestamp": "2026-08-13T09:01:03.204Z"
}

对于与身份验证相关的错误，请验证您的请求是否在 Authorization 标头中包含有效的 API 令牌。有关更多信息，请参阅 身份验证。

相关文章
这是否解答了您的问题？