WhatsAppの連絡先メモ：非公開の表示名を設定・解除する

UnifyPortでWhatsAppの連絡先に非公開の表示名を設定するには、POST /v1/accounts/{account_id}/contacts/note に contact_id と文字列の note を送ります。解除する場合は note: "" を明示します。変更対象はアカウント側の連絡先メモです。顧客の公開プロフィール、チャットメッセージ、担当者個人のCRM上の別名ではありません。

要点

• 現在の対応プロバイダーは whatsapp です。whatsapp-protocol や全チャネル共通の機能ではありません。
• note は必須です。空文字列は解除、未編集のフォームはリクエストなしとして扱います。
• 「アカウントのみで表示」は、共有受信箱で担当者ごとに閲覧権限が分離されるという意味ではありません。
• メモの書き込み、連絡先名の同期、メッセージ送信は別々に処理します。

どの名前を変更するのか

WhatsAppの連絡先管理に関する公式発表は、リンク済みデバイスでの連絡先管理を紹介しています。これはアカウント側データの背景であり、UnifyPortのメモ操作の仕様ではありません。

目的	適切な保存先・操作
接続アカウント用の連絡先表示名	UnifyPortの連絡先メモ
一人の担当者だけが見る別名	アプリ独自の保存領域と権限管理
プロバイダーから届くアドレス帳の名前変更	名前同期用の独立したデータビュー
チャットで連絡先情報を共有	連絡先カードの送信

名前変更の受信には、contact.updatedによる名前同期を参照してください。このイベントはニックネームを上書きせず、メモ保存の確認通知としても保証されていません。連絡先の登録や共有が目的なら、連絡先追加とvCard送信の違いが該当します。

画面上でも「アカウントのメモ」と「自分用の別名」を分けましょう。両方を「非公開の名前」と表示したまま、保存先だけを変える設計は混乱を招きます。

WhatsAppの連絡先メモを設定・解除する

連絡先メモのAPIリファレンスに、メソッド、入力、成功レスポンスが定義されています。プロバイダー別操作一覧を確認してから保存ボタンを有効にしてください。LINEとWhatsAppを同じ画面で扱う場合も、LINEで同じ書き込みができるとは限りません。

サーバー側でワークスペースのAPIキーと対象のメッセージングアカウントを用意し、連絡先取得の仕様に沿って同じアカウント内の対象を確認します。識別子は不透明な文字列として保持し、表示名から生成したり、全操作が同じ形式を受け付けると仮定したりしないでください。

フィールド	用途
contact_id	操作対象の連絡先
note	カスタム表示名。"" で既存のメモを解除

次のJavaScript関数は、文書化された呼び出しの例です。バックエンドで選択した実際の識別子を渡し、APIキーは保護された設定から読み込みます。自動リトライや受信箱全体の実装は含みません。

async function setContactNote({ apiKey, accountId, contactId, note }) {
  if (typeof note !== 'string') throw new TypeError('note must be a string');
  if (!accountId || !contactId) throw new Error('Select account and contact');

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

保存には利用者が確認した文字列を、解除には同じ関数へ空文字列を渡します。フォームの未指定値を空文字列に置き換えないでください。「未編集」が解除になってしまいます。null はアプリ側で拒否し、独自の解除表現を作らないようにします。

仕様上の成功は 200 OK と data.ok: true です。結果を確認してから保存済みにしてください。fetch が完了しただけでは成功とは限りません。

古いリクエストで新しい編集を上書きしない

以下はアプリ設計上の推奨事項であり、追加のAPIフィールドやサーバーの同時実行保証ではありません。

1. ワークスペース、メッセージングアカウント、連絡先で編集とジョブの範囲を区切る。同じ名前を識別キーにしない。
2. 未変更、編集済み、明示的な解除を区別し、必要に応じて解除の確認を求める。
3. 同じ対象への書き込みはアプリ内で直列化する。二重クリックと送信前の古いジョブを排除する。
4. 保持ポリシーに従い、要求値、結果、request_id を記録する。APIキーはログに残さない。
5. タイムアウト時は結果不明と表示する。別の編集者が新しい値を保存している可能性があるため、古い値を自動再送しない。

アプリ内の直列化では、すべてのリンク済みクライアントを調整できません。公開リファレンスには、バージョン前提条件、メモ専用の読み戻しフィールド、必ず届くメモ変更webhookは定義されていません。存在しないフィールドで確認処理を組まず、管理されたテストでアカウント側の挙動を確認してください。結果を観測できない場合は不明のまま扱います。

エラーリファレンスでは、サーバーまたは上流のメモ操作失敗を set_contact_note_failed、未対応操作を unsupported_by_provider としています。未対応機能に同じリクエストを繰り返しても解決しません。

確認項目とFAQ

設定、置き換え、明示的な解除、未編集フォーム、文字列以外の入力、競合する編集、未対応プロバイダー、タイムアウトをテストしましょう。これは推奨テストであり、実運用での検証結果ではありません。

サポートチケットの非公開メモですか？

いいえ。仕様では連絡先のカスタム表示名です。長い対応履歴や機密性の高い担当者コメントは、権限管理されたCRMに保存してください。

解除すると連絡先も削除されますか？

いいえ。解除するのはメモです。連絡先やメッセージの削除操作ではありません。

LINE、Zalo、WhatsApp Protocolにも使えますか？

現在の操作一覧で対応しているのは whatsapp のみです。UnifyPortの非公式インターフェースは共通のAPI形式を提供しますが、チャネルごとの機能は異なります。

contact.updatedを保存確認に使えますか？

いいえ。アドレス帳の名前変更イベントであり、カスタムメモ保存の確実な受領通知ではありません。

次のステップと出典

連絡先メモの設定を確認し、管理下の連絡先でテストしてから共有受信箱の編集機能を有効にしてください。

確認日：2026-10-13。

• UnifyPort：連絡先メモの設定
• UnifyPort：プロバイダー別操作
• UnifyPort：標準イベント
• WhatsApp：連絡先管理の公式発表