← 全記事
チュートリアル

WhatsAppグループ招待リンクをAPIで取得する：取得とリセットの違い

UnifyPortでWhatsAppのグループ招待リンクを取得するには、GET /v1/accounts/{account_id}/groups/invite-code にクエリパラメーター group_id を指定します。レスポンスには data.invite_url と data.invite_code が含まれます。取得はリセットではありません。 WhatsAppには管理者が既存リンクを無効にして新しいリンクを作る機能がありますが、UnifyPortの公開リファレンスが定義しているのは取得操作です。

要点

  • メッセージングアカウントと対象グループをセットで選びます。招待コードはグループIDではありません。
  • 取得はバックエンドで行い、権限のある担当者だけに表示します。
  • 取得、共有、参加承認、リセットを別の操作として設計します。
  • WhatsApp側でリセットしたら再取得し、自社アプリが管理するコピーを更新します。

招待リンクAPIが行うこと

WhatsAppの公式グループ招待ガイドは、リンクでの招待と、そのリンクが受信者から転送され得ることを説明しています。また、管理者が招待リンクを無効にして新しいリンクを作成する操作も案内しています。これをAPIの読み取り操作と混同しないでください。

UnifyPortの招待リンク取得リファレンスの契約は次のとおりです。

入出力意味
パスの account_id操作に使う接続済みメッセージングアカウント
クエリの group_idプロバイダー側のグループ識別子
data.invite_url返された招待URL
data.invite_code返された招待コード。会話IDではない

現在の操作対応表では、この操作は whatsapp に対応しています。LINE、Telegram、Zalo、別プロバイダーの whatsapp-protocol には対応していません。LINEとWhatsAppを同じ管理画面に並べる場合も、招待リンクボタンを共通機能として有効にしないでください。

リファレンスは、多くのプロバイダーでグループ管理者権限が必要だと説明しています。この手順では、利用を許可されたWhatsAppグループ管理者アカウントを使い、現在の権限を確認します。ワークスペースのAPIアクセス権がグループ管理権限を与えるわけではありません。これは接続済みアカウント向けの非公式インターフェースであり、WhatsApp Cloud APIのエンドポイントではありません。

APIキーを公開せずに取得する

まずグループ一覧から、対象アカウントが参加しているグループを選びます。この一覧にはメッセージのやり取りがないグループも含まれます。ページを順に取得し、選択した項目の id を保存してください。グループでは conversation_id と id は同じ値です。重複し得る表示名だけで選択しないようにします。

以下は実行済みテストではなく、リクエスト例です。環境変数にはバックエンドで保管するAPIキー、選択したアカウント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から招待URLを推測して組み立ててはいけません。失敗した場合や期待するリンクがない場合は、エラーまたは取得不可として表示します。

診断用にはHTTPステータス、エラーコード、サーバーの request_id を記録します。リクエスト追跡ガイドでは、レスポンス全体を記録せずに証拠を残す方法を説明しています。今回のレスポンスには招待リンクがあるため、分析データや一般ログに保存しない設計が重要です。

操作の目的ごとにボタンを分ける

ボタン目的意味しないこと
現在のリンクを表示APIの結果を取得して表示新しいリンクの作成
リンクをコピー許可された共有先へのコピー相手の参加完了
参加申請を確認承認フローを開くリンクのリセット
リンクをリセットWhatsAppの管理者操作へ案内公開済みUnifyPortリセットAPIの存在

表示やコピーの前に、アプリ側の操作権限を確認します。公開ダッシュボード、サポート用スクリーンショット、分析イベントの属性にリンクを含めないでください。キャッシュするなら「以前取得したリンク」と明示し、現在も有効だとは保証しません。

参加承認が必要なら、WhatsApp参加申請の承認キューを参照し、保留中の申請を確認してから判断します。リンクの取得によって承認機能が有効になったり、申請が承認されたりすることはありません。

WhatsAppでリセットした後の更新手順

仮の例として、リンクが広く転送されたため管理者がWhatsAppでリセットした一方、自社アプリには古いURLが残っている場合を考えます。

推奨する運用手順は次のとおりです。

  1. 管理者が操作する間、キャッシュ済みリンクの配布を止めます。
  2. 同じアカウントとグループで招待リンクを再取得します。
  3. 取得した結果を権限のある担当者に提示して確認します。
  4. アプリで管理するリンクと、旧URLから生成したQRコード画像を更新します。
  5. その他の配布先を管理する担当者にもコピーの確認を依頼します。

これはアプリの運用上の提案であり、アトミックな更新機能ではありません。公開リファレンスには、リセットパラメーター、リセット用エンドポイント、有効期限フィールド、専用のリセット確認webhookは定義されていません。フィールドを推測したり、イベントが来ないことを「変更なし」の証拠にしたりしないでください。再取得に失敗したら配布停止または未確認の状態を維持し、古い値へ黙って戻さないようにします。

FAQ

invite-codeを呼ぶたびに新しいリンクが作られますか？

定義されているのはリンクとコードの取得です。毎回の生成や更新は保証されていません。

invite_codeをgroup_idとして使えますか？

使えません。接続アカウント配下で選択したプロバイダーのグループIDを使います。招待コードは別の戻り値です。

このAPIでリセットできますか？

現在の公開リファレンスにリセット操作はありません。WhatsAppの管理者機能で操作し、その後にリンクを再取得してください。

取得失敗はグループ削除を意味しますか？

いいえ。HTTPステータスとエラー詳細を確認します。get_group_invite_code_failed はサーバー側または上流の取得失敗であり、削除の証拠ではありません。

次の手順と参照資料

まず招待リンク取得の読み取りフローを実装してください。公開前に、グループ選択、権限不足、クエリエンコード、ログの秘匿化、許可されたリセット後のコピー更新を確認します。これは提案する検証項目であり、実施済みの結果ではありません。

確認日：2026-10-15。

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。

API Key を取得API リファレンスを見る