← 全記事
チュートリアル

WhatsAppグループの名前・説明・画像をAPIで変更する

UnifyPortでWhatsAppグループの名前・説明・画像を変更するには、POST /v1/accounts/{account_id}/groups/update-info に group_id と、name、description、avatar_url のうち少なくとも1項目を送信します。このエンドポイントにはグループ管理者権限が必要です。担当者が変更する項目だけを送り、その後にグループ情報を再取得してください。編集画面を開いた時点の値が、現在も有効とは限りません。

要点

  • グループ情報はCRM内の非公開ラベルではありません。保存前に変更範囲を明示します。
  • 編集中は対象のメッセージングアカウントとグループIDを固定します。
  • 取得レスポンス全体を送り返さず、意図した変更だけを送信します。
  • 結果は項目ごとに確認します。タイムアウトやwebhookの未着は「変更されなかった」証拠ではありません。

設定を一括操作せず、変更項目を選ぶ

WhatsAppのグループ情報の変更ガイドは、公式アプリでの編集方法を説明しています。管理者設定のガイドには、メンバーによるグループ設定の編集を許可する設定もあります。ただし、これによってUnifyPortの契約が広がるわけではありません。グループ情報更新リファレンスは管理者権限を明示的に要求しています。

目的リクエスト項目別に扱うもの
グループ名を変更name受信トレイ内だけの別名
グループ説明を変更descriptionサポートチケットやメッセージ本文
グループ画像を変更avatar_url参加者のプロフィール画像

権限変更はグループ管理者の昇格・降格、招待の配布はグループ招待リンクの取得として分離します。情報編集フォームに混在させないでください。

UnifyPortは非公式インターフェースです。チャネル別操作対応表で、この書き込み操作は whatsapp のみに対応しています。LINE、Telegram、独立した whatsapp-protocol は対象外です。LINEも同じ受信トレイで扱う場合、グループ情報を取得できることと編集できることを区別してください。

最新の取得結果を基準に編集する

対象アカウントのグループ一覧からグループを選び、ページネーションも処理します。返された id を保持してください。グループでは conversation_id と id が同じ値です。名前は表示用であり、一意の識別子ではありません。

続いてグループ情報取得で現在の情報を読み込み、アプリ内では次を分けて保存します。

  1. 最後に取得した値。
  2. 担当者が実際に編集した項目。
  3. 送信後に改めて取得した値。

説明だけを変える場合、古い名前や画像は送信しません。再取得によって編集中の項目に別の変更が見つかったら、保存前に担当者へ確認を求めます。これはアプリ側の保護策であり、サーバーのバージョン検証機能ではありません。

確認画面にはアカウント、グループ、変更項目を表示します。API keyはバックエンドに保存し、担当者の操作権限もバックエンドで検証してください。

意図した変更だけを送信する

以下はバックエンドから1回のリクエストを行うJavaScript例です。実際に選択した識別子と、サーバーで管理するAPI keyを渡します。この例は空でない値への置換だけを許可し、説明の消去や画像の削除は定義しません。

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

edits には編集済みの項目だけを含めます。画像には公開アクセス可能なURLが必要です。自分たちで管理でき、公開する権利のある画像を使ってください。ローカルファイルのパスや、ブラウザーでのログインが必要なページは適切ではありません。これはURLを渡す操作であり、画像アップロードのエンドポイントではありません。

文書化された成功レスポンスは 200 OK と data.ok: true です。成功表示の前に両方を確認します。本番コードではネットワーク障害やJSON以外のレスポンスも扱い、取得できた request_id を保存し、認証情報はログに残さないでください。この例は説明用で、ここでは実行していません。

フォームの再送ではなく、項目ごとに結果を確認する

リクエスト後に同じグループを再取得し、名前と説明を送信値と比較します。画像は返された画像や公式アプリで確認してください。戻り値のURLが送信元URLと同じになる保証はありません。

標準イベントのリファレンスでは、group.updated の data.changes[] に複数の変更が含まれる場合があります。

  • renamed は name を持ちます。
  • description_changed は description を持ちます。
  • WhatsAppの avatar_changed は removed と任意の picture_id を持ち、画像URLは持ちません。

イベントは再確認のきっかけとして使い、各リクエストに必ず届く受領証とは扱わないでください。webhook配信仕様に従って署名を検証し、重複や順序の前後に対応します。イベントに項目がないからといって、無関係な値を消去してはいけません。

タイムアウト時は結果を未確定とし、現在の状態を調べてから残りの変更を判断します。古い複数項目のフォームを自動再送したり、古い状態に自動復元したりしないでください。公開リファレンスには複数項目のアトミックなロールバックやバージョン前提条件はありません。上流の権限拒否は update_group_info_failed として返されますが、同じエラーの原因が常に権限とは限らないため、詳細を確認します。

よくある質問

空の値で説明や画像を削除できますか？

この手順ではそう仮定しません。引用したエンドポイントには消去の規約がありません。目的の操作の契約を確認するまで、そのコントロールは有効にしないでください。

情報を取得できれば編集もできますか？

いいえ。読み取り権限、チャネルの操作対応、グループ管理者権限は別々の確認事項です。

3項目すべてを送る必要がありますか？

いいえ。group_id と少なくとも1つの編集項目を送ります。変更のないフォームから書き込みリクエストを送る必要はありません。

次のステップと出典

グループ情報更新リファレンスを基に実装してください。有効化前に、名前だけの変更、未編集フォーム、公式アプリでの同時編集、アクセスできない画像、権限拒否、タイムアウトを試します。これは推奨テストであり、実施済みの結果ではありません。

確認日：2026-10-23。

UnifyPort API

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

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

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