WhatsAppのチャットを別のラベルへ移す：安全なAPI引き継ぎ手順

UnifyPortでWhatsAppのチャットを業務ラベル間で移すには、所属変更を2回行います。移動先ラベルを追加し、結果を確認してから移動元ラベルを外します。 公開仕様には、これらを一括で確定するアトミックな移動操作はありません。関係のないラベルを残し、結果が不明な引き継ぎは未完了として表示してください。ラベル自体の削除や、タイムアウトを根拠にした「変更なし」の判定は適切ではありません。

要点

• action: "remove" は選択した会話からラベルを外す操作です。ラベル自体の削除とは異なります。
• 複数のラベルは共存できます。担当者や業務段階を必ず1つにする制約にはなりません。
• 追加を先にすると表示を維持しやすくなりますが、途中では両方のラベルが付きます。
• 担当割り当ての正本と引き継ぎの進捗は、アプリケーション側で管理します。

ラベル全体の置換ではなく、引き継ぎを定義する

WhatsAppのラベルのヘルプでは、ラベルによる整理と、1つのチャットへの複数ラベルの適用を説明しています。また、ラベルからリストへ段階的に移行しているとの記載があります。この画面上の用語変更は、UnifyPortの label_id が改名されたことや、アプリ内の全リストに対応APIがあることを意味しません。

仮の業務フローを考えます。チャットには「受付待ち」と「VIP」が付き、担当者が「対応中」に移したいとします。必要なのは「対応中」の追加と「受付待ち」の解除です。「VIP」は残します。「全ラベルを対応中で置き換える」処理ではありません。

6月のAPI更新ではラベル操作を紹介しました。引き継ぎ時は、操作対象の違いが重要です。

目的	操作	対象
分類の作成・名称変更	ラベルの作成または更新	ラベル定義
移動先を付ける	所属変更 action: "add"	そのラベルに属する選択済み会話
移動元を外す	所属変更 action: "remove"	そのラベルに属する選択済み会話
分類を廃止する	ラベル削除	会話1件の所属ではなく、ラベル自体

他のチャットも同じ分類を使っている可能性があります。1件の所属解除をラベル削除で代用しないでください。

2つの操作を準備する

選択したメッセージングアカウントでラベル一覧を取得し、移動元と移動先のIDを確定します。ページネーションを最後まで確認し、表示名を識別キーにしないでください。移動先を新規作成する場合は、ラベル作成・更新の結果にある data.id を保存します。

同じアカウントでチャットの conversation_id を特定します。ラベル名、連絡先の表示名、メッセージIDは会話IDの代わりになりません。操作対応表も確認してください。このラベル操作は現在 whatsapp 向けで、LINE、Telegram、Zalo、別プロバイダーの whatsapp-protocol には対応していません。LINEとWhatsAppを同じ受信箱で扱う場合も、LINE用の分類はアプリ側で別に設計する必要があります。

ラベル所属変更のリファレンスは、POST /v1/accounts/{account_id}/conversations/labels に label_id、action、空でない conversation_ids 配列を送る仕様です。

次のサーバー側JavaScriptは、意図的に1回の操作だけを行います。バックエンドで選択した実際のIDと、安全に保存したAPIキーを渡してください。説明用コードであり、検証済みの本番クライアントではありません。

async function changeLabelMembership({
  apiKey, accountId, labelId, conversationIds, action
}) {
  const validId = value => typeof value === 'string' && value.trim() !== '';
  if (!validId(accountId) || !validId(labelId) ||
      !Array.isArray(conversationIds) || conversationIds.length === 0 ||
      !conversationIds.every(validId) || !['add', 'remove'].includes(action)) {
    throw new Error('Select an account, label, conversations, and action');
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/conversations/labels`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        label_id: labelId,
        action,
        conversation_ids: [...new Set(conversationIds)]
      })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

最初は移動先IDと add、後で同じチャットに対して移動元IDと remove を指定します。移動元と移動先が同じIDなら、アプリ側で拒否してください。HTTPステータスとレスポンスを確認します。fetch が正常終了しただけでは成功とは限りません。文書化された成功データには、対象の label_id、action、conversation_ids が含まれます。

追加と解除の間に確認を挟む

以下はアプリケーションの設計上の推奨事項であり、UnifyPortのトランザクション保証ではありません。

1. アカウント、会話、移動元、移動先をローカルに保存し、担当変更の権限を確認します。
2. 移動先を追加します。APIキーを除き、レスポンスと request_id を記録します。
3. 明示的な label_id で会話一覧を取得し、移動先に選択したチャットが現れたことを確認します。
4. 移動元の所属だけを解除し、VIPなど独立したラベルは残します。
5. 両方の表示を照合します。予定どおりでなければ、未完了の作業として残します。

移動先の確認に、ラベル未指定の一覧を使わないでください。WhatsAppでは label_id を省略すると、仕様上は特別に注目している会話だけが返ります。チャットが一覧にない場合のラベル絞り込みガイドで、この範囲とページネーションを説明しています。最初のページにないことは不在の証拠ではなく、読み取り失敗は空の結果でもありません。ライブの複数ページ読み取りは、不変のスナップショットとして保証されていません。

観測した所属	今回の引き継ぎでの解釈	推奨対応
移動元のみ	移動先をまだ確認できない	移動元を残し、追加処理を調べる
両方	中間状態、または別の編集	現在の意図を確かめてから移動元を外す
移動先のみ	予定した所属パターンを観測	ローカルの担当割り当ても一致すれば完了を記録
どちらもない、または読み取り不完全	未解決	ローカル作業を保持して調査する

古い意図を再実行せずに復旧する

同じ会話へのアプリ側の変更は直列化し、送信前に古くなったキュー作業を除外します。別の担当者が割り当てを変えたなら、古い引き継ぎをそのまま完了させないでください。ローカルの直列化で全リンク済みクライアントをロックすることはできないため、外部変更も照合します。

追加がタイムアウトしたら移動元を保持し、移動先を読んでから次の判断をします。解除結果が不明なら、両方を確認してから再実行を検討します。移動先を自動で外して「元に戻す」のも避けてください。他の担当者が既にそのラベルを使っている可能性があります。

公開仕様には、2回の呼び出しをまたぐ原子性、バッチ全体の全成功・全失敗、バージョン前提条件、専用のラベル変更webhookの保証はありません。バッチでも会話ごとに進捗を保持します。set_label_members_failed はサーバー側または上流の失敗、unsupported_by_provider は機能非対応を示します。非対応を無限に再試行しても解決にはなりません。

よくある質問

新しいラベルを追加すると古いラベルは外れますか？

いいえ。APIには追加と解除が別々にあります。各ラベルの所属を独立に扱ってください。

ラベルだけで担当者を必ず1人にできますか？

この仕様では保証できません。担当者と権限はアプリ側に保存し、ラベルはその決定をプロバイダー側へ反映する表示として使います。

conversation.updated で引き継ぎ完了を確認できますか？

その前提にしないでください。文書化されている設定はミュート、アーカイブ、ピン、既読などで、ラベル所属変更の受領通知は保証されていません。

WhatsApp Cloud APIの公式操作ですか？

いいえ。接続済みアカウント向けのUnifyPort非公式インターフェースです。WhatsAppのアプリヘルプは利用者向け概念を説明するもので、このAPI仕様ではありません。

次のステップと参照資料

会話へのラベル追加・解除を確認し、管理下のアカウントで正常な引き継ぎ、追加失敗、解除タイムアウト、競合編集、ページネーション、無関係なラベルの保持をテストしてから一括操作を有効にしてください。これは推奨テストであり、実施済みの結果ではありません。

確認日：2026-10-14。

• UnifyPort：ラベル所属変更
• UnifyPort：会話一覧
• UnifyPort：標準イベント
• WhatsApp Help Center：How to use labels