透過 API 取得 WhatsApp 群組邀請連結：讀取與重設的差別

透過 UnifyPort 取得 WhatsApp 群組邀請連結，請呼叫 GET /v1/accounts/{account_id}/groups/invite-code，並以查詢參數傳入 group_id。回應包含 data.invite_url 與 data.invite_code。讀取連結不等於重設連結。 WhatsApp 提供管理員停用原連結並建立新連結的原生功能；UnifyPort 公開文件描述的是讀取，並非重設。

重點整理

• 一併確認訊息帳號與目標群組；邀請碼不是群組 ID。
• 在後端讀取，只向獲授權的操作人員顯示連結。
• 取得、分享、加入審核與重設是不同操作。
• 原生重設後重新讀取，並替換應用程式能管理的副本。

邀請連結端點的實際用途

WhatsApp 的官方群組邀請說明介紹連結邀請，並提醒收件者可能繼續轉傳。文件也說明管理員可停用群組邀請連結並建立新的連結。這項原生功能與 API 讀取不可混為一談。

UnifyPort 取得群組邀請連結文件定義的範圍如下：

輸入或輸出	意義
路徑中的 account_id	執行操作的已連結訊息帳號
查詢參數 group_id	平台群組識別碼
data.invite_url	回傳的邀請網址
data.invite_code	回傳的邀請碼，不是對話 ID

目前操作支援矩陣將此功能對應至 whatsapp，不包括 LINE、Telegram、Zalo 或獨立的 whatsapp-protocol。端點說明提醒，多數平台需要群組管理員權限。本流程請使用獲授權的 WhatsApp 群組管理員帳號，並確認目前權限；工作空間的 API 存取權並不授予群組管理權。

這是已連結帳號的非官方接口，不是 WhatsApp Cloud API 端點。

安全讀取，不把 API Key 交給瀏覽器

先透過群組清單在正確帳號下選擇群組。清單包含帳號已加入但尚未用於傳訊的群組。依分頁讀取並保存選中項目的 id；群組的 conversation_id 與 id 相同。不要只用可能重複的顯示名稱識別群組。

以下是示範請求，並非執行紀錄。環境變數應分別使用後端保存的 API Key、選定帳號 ID，以及清單回傳的群組 ID：

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/groups/invite-code" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "group_id=${WHATSAPP_GROUP_ID}"

平台識別碼可能包含 @ 等字元，因此查詢參數必須正確編碼。金鑰留在伺服器，不要把此驗證請求放進瀏覽器 JavaScript。

成功後讀取 data.invite_url 與 data.invite_code，不要從群組 ID 猜測邀請網址。若請求失敗或缺少預期連結，介面應顯示錯誤或暫時無法取得，而非自行補值。

保留 HTTP 狀態、錯誤碼及伺服器 request_id 供診斷。請求追蹤指南說明如何保留證據而不記錄整份回應。此處回應含邀請連結，不應寫入分析屬性或一般應用程式日誌。

讓不同按鈕對應不同意圖

控制項	預期行為	不代表
顯示目前連結	讀取並顯示 API 結果	已建立新連結
複製連結	複製目前網址供授權分享	對方已加入群組
審核加入申請	開啟審核流程	連結已重設
重設連結	引導管理員使用 WhatsApp 原生功能	存在公開的 UnifyPort 重設呼叫

顯示或複製前，先檢查應用程式的操作權限。避免將連結放上公開儀表板、客服截圖或分析事件屬性。若快取結果，應標示為「先前取得的連結」，而非保證目前有效。

需要入群審核時，請參考 WhatsApp 群組加入申請審核佇列，先核對待處理申請再決策。取得邀請連結不會開啟審核，也不會核准申請人。

原生重設後，更新應用程式保存的副本

以下是假設情境：管理員認為連結分享範圍過廣，於是在 WhatsApp 重設，但應用程式仍保留舊網址。

建議作業流程：

1. 管理員完成原生操作前，暫停分享快取連結。
2. 對同一帳號、同一群組重新讀取邀請連結。
3. 將剛取得的結果交由授權操作人員確認。
4. 替換應用程式管理的連結，以及用舊網址產生的 QR Code 圖片。
5. 通知其他分享管道負責人檢查各自的副本。

這是應用程式的管理建議，不是原子輪替功能。公開文件沒有定義重設參數、重設端點、連結到期時間欄位或專用重設確認 webhook。不要猜測欄位，也不要因沒有事件就判定狀態未變。若重新讀取失敗，維持暫停分享或明確標示待確認，不要默默恢復舊快取。

常見問題

每次呼叫 invite-code 都會建立新連結嗎？

文件描述的是取得連結與邀請碼，並未保證每次讀取都會輪替或建立新連結。

invite_code 可以當作 group_id 嗎？

不可以。請使用在該訊息帳號下選定的平台群組 ID；邀請碼是另一個回傳值。

可以透過此 API 重設連結嗎？

目前公開文件沒有重設操作。請使用 WhatsApp 原生管理員功能，再重新讀取目前連結。

讀取失敗表示群組已刪除嗎？

不表示。請查看 HTTP 狀態與錯誤詳情。get_group_invite_code_failed 是伺服器或上游讀取失敗，不是群組已刪除的證據。

下一步與資料來源

先依取得群組邀請連結實作唯讀流程。上線前檢查群組選擇、權限不足、查詢編碼、日誌遮蔽，以及經授權原生重設後的副本更新。這些是建議驗收項目，不是已執行的測試結果。

資料核對日期：2026-10-15。

• WhatsApp：建立群組與邀請成員
• UnifyPort：取得群組邀請連結
• UnifyPort：平台操作支援
• UnifyPort：錯誤參考