account.profile.updated で WhatsApp アカウント名を同期する

アプリに表示する接続済み WhatsApp アカウント自身の名前は、UnifyPort の account.profile.updated イベントで同期します。data.profile.display_name はビジネス名を優先し、なければプッシュ名を使用します。更新対象はアカウントのプロフィール表示であり、顧客の連絡先、社内ラベル、接続状態ではありません。文書化された発火元は WhatsApp の名前イベントで、全チャネル共通のプロフィール変更通知ではありません。

ポイント

• 名前ではなく、ワークスペース、provider、account_id で対象を特定する。
• アカウント設定の name とプラットフォーム上の公開名を分ける。
• full_sync はプロフィールの取得元を示し、メッセージ履歴の復元完了を意味しない。
• プロフィール通知だけで認証や接続の正常性を判断しない。

どの名前を表示するのか決める

サポート用のアカウント選択画面には、社内の運用ラベルとチャネル上の公開名を併記できます。名前の変更で担当者、ルーティング、権限まで変わる設計は避けましょう。

値・イベント	意味	推奨する表示先
アカウント設定の name	アカウント設定で管理するラベル	社内用の選択ラベル
data.profile.display_name	チャネルのプロフィールから得た公開名	公開名専用の行
data.profile.business_name / push_name	イベントに含まれる名前の構成要素	任意の詳細表示
contact.updated	連絡先のアドレス帳名	顧客の連絡先ビュー
account.status.updated	認証・ランタイムの状態	接続状態ビュー

顧客側の情報は連絡先名の同期ガイドで扱います。同じハンドラーで自分のアカウント名も更新すると、別の対象を書き換える危険があります。顧客メッセージの送信者名も、自分のアカウントの改名を示すものではありません。

Get account リファレンスは設定と provider_profile を別々に返すため、画面の初期読み込みに使えます。公開名がない場合は未取得と表示し、社内ラベルを観測済みの公開名として扱わないでください。

account.profile.updated の範囲を読む

以下はイベントリファレンスに沿った例です。値は文書のサンプルで、顧客の実測データではありません。

{
  "id": "evt_profile_7e91d2c4",
  "type": "account.profile.updated",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-08-28T09:51:51Z",
  "data": {
    "account": { "provider_account_ref": "provider_account_example" },
    "profile": {
      "display_name": "Example Business",
      "business_name": "Example Business",
      "push_name": "Example Account"
    },
    "event": {
      "kind": "account_profile_updated",
      "source": "self_rename"
    }
  }
}

独自の優先順位を設けず、提供された display_name を使います。ビジネス名が優先されていれば、push_name の変更が表示名に現れない場合もあります。

data.event.source の文書化された値は次のとおりです。

• self_rename：接続中のアカウントが自分の名前を変更した。
• full_sync：完全同期スナップショットからプロフィールを取得した。

どちらも操作した人物を特定しません。監査ログに架空の操作者を記録しないでください。また、full_sync は全メッセージ、連絡先、画像などの同期完了を保証しません。

アカウント表示を独立して実装する

推奨手順は以下です。

1. 必要な通知を購読する。 既存の購読と署名設定を維持して account.profile.updated を追加します。イベントフィルターガイドで明示的リストとワイルドカードの違いを確認できます。
2. 検証して永続化する。 配信仕様に従い、signing_secret を使って X-Device-Timestamp、ピリオド、未加工の本文に対する16進 HMAC-SHA256 を検証し、タイムスタンプの鮮度も確認します。認証済みイベントを永続化してから 2xx を返します。
3. 既存アカウントを特定する。 受信側のワークスペースと、エンベロープの provider、account_id を使います。新しい名前を理由に別アカウントを作成したり、会話を移動したりしません。
4. プロフィール表示だけ更新する。 社内ラベル、顧客名、認証、ランタイム状態は変更しません。名前は HTML ではなくテキストとして描画します。
5. 取得元をローカルに記録する。 イベント ID、発生時刻、source を表示データに関連付けます。これはアプリ側の記録設計であり、追加の API フィールドではありません。

この JavaScript は検証済みイベントから表示候補を取り出すだけです。永続化、順序制御、受信サーバー全体は実装していません。

function profileNameCandidate(event) {
  if (event.type !== 'account.profile.updated' ||
      event.provider !== 'whatsapp') return null;
  if (typeof event.account_id !== 'string' || !event.account_id) {
    throw new Error('Missing account identity');
  }
  const name = event.data?.profile?.display_name;
  if (typeof name !== 'string') {
    throw new Error('Profile display name needs review');
  }
  return { accountId: event.account_id, displayName: name };
}

戻り値のキーはアプリ内の変数です。名前が欠けている、または型が不正なら、全プロフィールを既定値で置き換えず、イベントを確認用に保持します。空文字列には「名前を取得できません」などのローカル表示方針を定めます。連絡先イベントのクリア規則をこの仕様に持ち込まないでください。

古いイベントと初期読み込みを調整する

通常イベントの再配信はイベント ID で重複排除します。配信順序は保証されないため、プロフィールイベントには occurred_at、同時刻ならイベント ID による決定的な順序を使い、処理済み記録と表示更新をまとめてコミットします。

ここでは REST 読み込みと Webhook が共通のプロフィール版番号を持つとは文書化されていません。初期読み込み中にイベントを適用した場合、遅れて返る読み込み結果で上書きしないようにします。初期化とイベント処理を直列化するか、読み込みを基準にして蓄積したイベントを後から適用してください。矛盾があれば照合対象とし、上流の因果順序を完全に再現できると主張しないことが重要です。

UnifyPort は非公式インターフェースです。このイベントはネイティブのプロフィールを書き換える命令でも、完全なアーカイブや再配信保証でもありません。LINE と WhatsApp を同じ画面で扱う場合も、LINE、Zalo、Telegram、whatsapp-protocol が同じイベントを出すと推測しないでください。

FAQ

push_name が変わったのに display_name が同じなのはなぜですか？

BusinessName が優先され、なければ PushName が使われます。まず各要素を確認し、表示が変わらないだけで同期失敗と判断しないでください。

full_sync はメッセージ履歴の完全同期を意味しますか？

いいえ。このプロフィールイベントの取得元を示すだけです。

イベント受信後に PATCH で name を変更すべきですか？

自動同期としては不要です。それは観測した公開名の表示ではなく、アカウント設定の変更になります。社内ラベルの編集は独立した明示的操作にしてください。

次のステップと参考資料

アカウントプロフィールイベントに沿って表示カードを実装します。両方の source、異なるビジネス名とプッシュ名、重複・古いイベント、欠損・空の名前、遅い初期読み込みをテストしてください。顧客の連絡先、社内ラベル、接続状態が変わらないことも確認します。これは推奨テストであり、実行済みの結果ではありません。

確認日：2026-11-05。

• UnifyPort：account.profile.updated
• UnifyPort：Get account
• UnifyPort：Webhook 配信仕様