總覽
使用 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 憑證儲存在環境變數或秘密管理工具中。
可用端點
方法 | 端點 | 說明 |
|
| 建立 WhatsApp 群組 |
|
| 刪除 WhatsApp 群組 |
|
| 發送邀請至待處理聯絡人 |
|
| 從群組中移除參與者 |
|
| 列出有效的 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"
}請求主體參數
欄位 | 類型 | 說明 |
| string | 要使用的頻道。若省略，則使用預設頻道。 |
| string | WhatsApp 群組名稱。 |
| string | WhatsApp 群組說明。 |
| string | 群組擁有者的電子郵件地址。 |
| array | 要加入群組的操作員電子郵件地址。 |
| array | 要加入群組的聯絡人的電話號碼、BSUID 或 ContactId。每個群組最多 7 名聯絡人。 |
| 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"
}
}回應代碼
代碼 | 說明 |
| 群組建立成功。 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
2. 刪除 WhatsApp 群組
DELETE /api/ext/v3/conversations/groups/{groupId}
刪除指定的 WhatsApp 群組。
如果群組已被刪除，該端點仍會回傳 200 OK。
路徑參數
參數 | 類型 | 必要 | 說明 |
| string | 是 | 要刪除的群組 ID。 |
回應
成功的請求會回傳 200 OK。
{
"result": true
}回應代碼
代碼 | 說明 |
| 群組刪除成功。 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
3. 發送群組邀請
POST /api/ext/v3/conversations/groups/{groupId}/invites
向所有仍處於待處理狀態的聯絡人發送群組邀請。
API 會檢查群組中的聯絡人，識別那些加入狀態為「待處理」的聯絡人，並將群組邀請範本發送至每位聯絡人的 1:1 對話中。
路徑參數
參數 | 類型 | 必要 | 說明 |
| 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：每位待處理聯絡人的邀請結果。
回應代碼
代碼 | 說明 |
| 邀請結果回傳成功。 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
4. 從 WhatsApp 群組移除參與者
DELETE /api/ext/v3/conversations/groups/{groupId}/participants
從 WhatsApp 群組中移除操作員及/或聯絡人。
您必須提供至少一個操作員電子郵件或聯絡人目標。
路徑參數
參數 | 類型 | 必要 | 說明 |
| string | 是 | 要移除參與者的群組 ID。 |
請求主體
{
"operator_emails": [
"[email protected]"
],
"contact_targets": [
"14155551234"
]
}請求主體參數
欄位 | 類型 | 說明 |
| array | 要從群組中移除的操作員電子郵件地址。 |
| array | 要加入群組的聯絡人的電話號碼、BSUID 或 ContactId。每個群組最多 7 名聯絡人。 |
您可以提供 operator_emails、contact_targets 或兩者皆提供。必須至少提供其中一項。
回應
成功的請求會回傳 200 OK。
{
"result": true
}回應代碼
代碼 | 說明 |
| 參與者移除成功。 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
5. 列出有效的 WhatsApp 群組
POST /api/ext/v3/conversations/groups/list
回傳分頁游標的有效 WhatsApp 群組清單。
您可以選擇依據頻道或特定群組 ID 篩選結果。如果您未指定頻道，將使用預設頻道。
請求主體
{
"channel": "MyChannel",
"limit": 20
}請求主體參數
欄位 | 類型 | 說明 |
| string | 要使用的頻道。若省略，則使用預設頻道。 |
| 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
}分頁
「列出群組」端點會以分頁形式回傳結果。
如果有更多群組，回應會包含一個 continuous_token。請使用此 token 來檢索後續頁面。
當 continuous_token 不存在或為 null 時，表示沒有更多結果。
回應代碼
代碼 | 說明 |
| 有效群組清單回傳成功。 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
錯誤回應
WhatsApp Groups API 端點可能會回傳以下 HTTP 狀態代碼：
代碼 | 說明 |
| 請求無效。 |
| 請求未經授權。 |
| 請求被禁止。 |
| 請求過多。 |
| 發生未預期的錯誤。 |
對於 400、403 和 500 回應，API 可能會回傳其他詳細資訊，例如錯誤代碼、訊息和時間戳記。
錯誤回應範例
{
"details": "string",
"code": 0,
"message": "string",
"timestamp": "2026-08-13T09:01:03.204Z"
}對於與驗證相關的錯誤，請確認您的請求在 Authorization 標頭中包含有效的 API 權杖。更多資訊請參閱 驗證。