whatsapp-management

WhatsApp 管理（Nexor 経由）

Nexor は、WhatsApp に関するあらゆる操作の窓口です。顧客が Meta や基盤となるプロバイダーに直接連絡することはありません。番号の接続でさえ、Nexor が生成するホスト型セットアップリンクを通じて行います。以下の各ツールは、API キーに基づいて自動的にテナントの範囲に限定されます。ユーザーから client_id を受け取ったり、ユーザーに渡したりしないでください。

テンプレートを作成する前やヘルス情報を解釈する前に、references/whatsapp-reference.md を読んでください。ここには、ほとんど変更されず、間違いやすい Meta の永続的なルール（テンプレートの書式、カテゴリ、品質評価、24 時間のウィンドウ）が記載されています。

用途別のツール

用途	ツール
番号を確認する	list_whatsapp_numbers
番号を接続する	connect_whatsapp_number → 顧客が開くホスト型セットアップリンクを返します
番号の不具合を修正する	reconcile_whatsapp_number。新たに Meta 認証が必要な場合は、再度 connect_whatsapp_number を実行します
エージェントに割り当てる	assign_whatsapp_to_workflow
番号を無効化／削除する	deactivate_whatsapp_number（元に戻せます）；disconnect_whatsapp_number（管理者向け、破壊的）
名前を変更する（内部ラベル）	rename_whatsapp_number
ビジネスプロフィール	get_whatsapp_business_profile、set_whatsapp_display_name、set_whatsapp_profile_photo
ヘルスとリスク	get_whatsapp_health
応答タイミング（デバウンス）	get_whatsapp_response_timing、set_whatsapp_response_timing
「テンプレートは承認済みですか／どれくらいかかりますか？」	get_whatsapp_template_approval_status
テンプレート — 読み取り	list_whatsapp_templates、get_whatsapp_template、check_whatsapp_template_approvals、sync_whatsapp_templates
テンプレート — 作成	review_whatsapp_template_drafts → create_whatsapp_templates_batch（推奨）；create_whatsapp_template（単一）
テンプレート — 整理	set_whatsapp_template_purpose、delete_whatsapp_template
送信頻度プール	get_template_pool、set_template_pool、set_opening_templates
メッセージを送信する	send_message

番号を接続する

1. connect_whatsapp_number → ホスト型セットアップリンクを返します。顧客にリンクを渡し、開くよう伝えてください。認証（Meta へのログイン、専用モード／共存モードの選択）はそこで行われ、チャット内では完了できません。
2. 完了すると、Nexor は番号を自動的に記録し、受信 Webhook を登録します。list_whatsapp_numbers で確認してください。
3. assign_whatsapp_to_workflow で番号をエージェントに割り当てます。これにより、受信メッセージがそのエージェントに届くようになります。
4. クライアントごとに上限があります（デフォルトは 10）。上限に達すると、connect_whatsapp_number は WHATSAPP_LIMIT_REACHED エラーで失敗します。

スクリプトで実行する OTP／確認手順はありません。プロビジョニングはすべてホスト型リンク上で行われます。接続済みの番号に後から不具合が発生した場合は、まず reconcile_whatsapp_number を実行してください。新しい Meta 認証が必要な場合に限り、セットアップリンクをもう一度送信します。

ヘルスとリスク

「WhatsApp にリスクはありますか／送信できないのはなぜですか／上限はいくつですか」には、その番号の get_whatsapp_health を使います。リスクは単一のフィールドではありません。以下をまとめて確認してください（詳細はリファレンスを参照）。

• quality_rating：GREEN（問題なし）・YELLOW（注意）・RED（Meta による制限のリスクあり）。
• messaging_health.can_send_message：AVAILABLE・LIMITED・BLOCKED。エンティティごと（WABA／電話番号）のエラーと推奨される修正方法も含まれます。
• messaging_limit：1 日あたりのティアと上限。
• route_verification：プロバイダーのルートが有効か、再接続／再同期が必要かを示します。「reconnect」と表示された場合は、reconcile_whatsapp_number を実行してください。

ヘルスを 1 回確認すると複数の Meta 呼び出しが発生するため、結果は短時間キャッシュされます。ループでポーリングしないでください。状態をわかりやすい言葉で要約し、具体的な次のアクションを推奨してください。

テンプレート

テンプレートの作成は、WhatsApp で最も価値の高いタスクです。テンプレートは決して汎用的なものではありません。 特定のエージェントに属し、そのエージェントのペルソナ、製品、目標、言語を反映します。 Meta の恒久的なルールとエージェントの目標別に整理されたスターターライブラリについては、references/whatsapp-reference.md を読んでください。この流れに沿って最初から最後まで進め、いきなり下書きに取りかからないでください。

1. 対象のエージェントを特定する — 決して省略しない

テンプレートは実在するエージェントの話し方に合わせる必要があります。対象が定まらないテンプレートを作成しないでください。

• 会話の対象がすでに1つのエージェントに絞られている場合は、それを使用します。
• そうでない場合は、list_workflows を使って選択肢を一覧表示し、どのエージェントかを尋ねてください。
• ユーザーがエージェントを指定せずに「予約確認テンプレート」を求めた場合、不足しているのはエージェントです。まずそれを特定してから、下書きを作成してください。

2. 下書きの前にエージェントのコンテキストを読む

get_workflow(workflow_id) を呼び出し、goal_type、基本プロンプト／ペルソナ、製品／会社、言語、接続済みチャネルを確認します。これにより、文面にコンテキストが反映されます。エージェントのトーンに合わせ、製品名を入れ、そのエージェントの言語で書いてください。汎用的な話し方をでっち上げないでください。エージェントが会議を予約するかどうかも確認します（goal_type が appointment、またはファネルに予約ステージがある場合）。これにより、会議用変数と確認／リマインダーのスターターセットを利用できるようになります。

3. コンテキストに合わせたスターターセットを提案する

references/whatsapp-reference.md のスターターライブラリから、エージェントの目標に合わせて2～4件の下書きを提示し、実際の製品、会社、ペルソナ、言語に合わせて調整します。目標に適したものを先に提示してください。

• 予約／確認エージェント → 予約確認（UTILITY、{{fecha}}／{{hora}}／{{link_reunion}}、確認＋再予約のクイック返信ボタン）、リマインダー、無断キャンセル後の再アプローチ。
• 販売／見込み客の選別／情報提供エージェント → 挨拶の導入文、フォローアップ、再アプローチ。

送信時に自動解決される Nexor の標準変数を優先してください。{{nombre}}、{{agente}}／{{ejecutivo}}、{{empresa}}、{{producto}}、会議用の {{fecha}}、{{hora}}、{{asesor}}、{{link_reunion}} を使用し、価値がある場合はエージェント独自のリードメタデータフィールドを追加します。ほかの名前も使用できますが、その場合は LLM による解決にフォールバックします。

4. ダッシュボードのフォームに従ってボタンと変数を正確に作成する

チャットはダッシュボードのテンプレートビルダーと完全に同等の機能を備えています。活用してください。

• ボタン：QUICK_REPLY、URL（url が必要）、PHONE_NUMBER（phone が必要）。合計最大10個、URL は2個以下、電話番号は1個以下です。URL ボタンの変数は URL の末尾に配置してください。クイック返信ボタンを URL／電話番号ボタンと交互に配置しないでください。ラベルは25文字以下です。
• 変数：{{...}} の形式で指定し、本文の先頭／末尾や隣接する位置には配置しないでください。すべての変数に variables 内で現実的な例を指定する必要があります。フッターに変数は使用できません。TEXT ヘッダーには変数を1つまで含められます。含める場合は専用の例が必要です。

5. 事前確認 → 承認 → 送信

1. review_whatsapp_template_drafts — 読み取り専用の事前確認です。オペレーターには、各下書きが WhatsApp のプレビュー（レビューカード）として表示され、有効性と問題点も示されます。返された normalized_templates、エラー、警告を提示してください。all_valid=true になるまで修正して再確認します（review_id が返されます）。
2. その下書きの内容を明示的に承認してもらいます。
3. その下書き、review_id、confirm=true を指定して create_whatsapp_templates_batch を呼び出します。確認をでっち上げてはいけません。（一括処理／レビューの手順が不要な場合は、単一テンプレート用の簡易手段 create_whatsapp_template を使用します。）

6. 承認済みテンプレートを該当エージェントの運用に組み込む

この手順によって、選択したエージェントでテンプレートが実際に適用されます — 作成したテンプレートは、用途が設定され、エージェントのプールに追加されるまでは機能しません。送信後、手順 1 の workflow_id に対して以下を行います。

• まだ internal_type（greeting / follow_up / reminder / reactivation）を渡していない場合は、set_whatsapp_template_purpose を使って各テンプレートの用途を設定します。
• get_template_pool で現在のプールを読み込み、set_template_pool でフォローアップ／リマインダー／再アクティベーション用のテンプレートを追加します（状態全体を置き換えるため、設定したいリスト全体を送信してください）。
• 初回連絡用の文面を set_opening_templates で設定します。
• get_template_pool で設定を再確認し、現在どのエージェントがどのテンプレートを使っているかを報告します。

7. 承認状況と設定を報告する

Meta の承認は非同期で行われるため、各テンプレートが APPROVED または REJECTED になるまで check_whatsapp_template_approvals を確認します。最後に、エージェント、テンプレート、その用途、およびプールへの設定を伝え、全体像をユーザーに示します。

• Meta では既存テンプレートをその場で編集できません。REJECTED のテンプレートを修正するには、新しい名前で作成し直して再送信します（プレビュー後、必要に応じて古いテンプレートを delete_whatsapp_template で削除します）。

「テンプレートは承認されましたか？」／「承認までどのくらいかかりますか？」

Nexor では、単に**「テンプレート」と言う場合は常に WhatsApp テンプレートを指します。そのため、限定のないテンプレートに関する質問（承認済みか、所要時間、一覧、編集など）はすべて WhatsApp のこととして扱います。また、テンプレートは完全に接続された WhatsApp 番号**に対してのみ存在します。番号が接続されていなければ、テンプレートに意味はありません。

これはテンプレートに関する最もよくある質問です。推測した時間ではなく、データに基づいて 1 つのツールで回答してください。

1. get_whatsapp_template_approval_status を呼び出します（最初に Meta から情報を更新するため、最新の状況が返されます）。no_whatsapp: true が返された場合、WhatsApp 番号はまだ接続されていません。テンプレートが 0 件だとは伝えず、まず番号を接続するようお客様に案内します（connect_whatsapp_number）。それ以外の場合、返されるのは一覧ではなく概要です。ステータス別の counts、all_approved／none、pending_hours（実際に待機している時間）が含まれる各 pending[] テンプレート、longest_pending_hours、some_pending_over_24h、Meta の reason を含む各 rejected[]、および review_window が返されます。
2. お客様の言語で、得られた情報に基づいて回答します。
   • all_approved: true → 「N 件のテンプレートすべてが承認されています ✅。」
   • 承認待ちがある場合 → 「N 件中 X 件が承認済みで、Y 件が Meta の審査中です。」根拠のない予測ではなく、標準的な審査期間を伝えます。承認は非同期で行われ、Meta が判断します。通常は数分から約 1 時間ですが、まれに 24～48 時間かかることがあります。 具体的に伝える場合は、pending_hours の実際の待機時間を示します（「最も長いものは約 3 時間審査中です」など）。
   • some_pending_over_24h: true → 通常より時間がかかっていると伝えます。約 48 時間を超えても審査中の場合は、新しい名前で修正して再送信するのが解決策です（Meta では既存テンプレートをその場で編集できません）。
   • rejected[] がある場合 → reason とともに対象のテンプレート名を伝え、新しい名前での修正を提案します。
   • none: true → テンプレートはまだありません。いくつかの案を作成することを提案します。
3. 正確な承認時刻を約束したり、短い間隔で繰り返し確認したりしないでください。質問 1 回につき、呼び出しは 1 回です。承認時期は実際に Meta が決定し、一定ではありません。

送信

send_message は whatsapp（メール／sms／通話にも対応）でリードにメッセージを送信します。24 時間のカスタマーサービス対応時間内であれば自由形式のテキストを送信できます。この時間を過ぎた場合は、承認済みの template_id を渡す必要があります。これにより会話を再開したり、初めて連絡したりできます。

応答タイミング

get_whatsapp_response_timing／set_whatsapp_response_timing で、受信メッセージのデバウンス（バッファ時間、約 5～60 秒）を制御します。リードから連続して届くメッセージをまとめて 1 回の返信にするために、Nexor が待機する時間です。長く設定すると、より自然な応答になりますが、少し遅くなります。

ガードレール

• client_id は決して渡さないでください。テナントはキーから判別されます。
• 破壊的な操作（disconnect_whatsapp_number、delete_whatsapp_template）は、プレビューと確認、または管理者による許可が必要です。まず顧客に確認し、変更内容を読み上げてください。
• 画像（set_whatsapp_profile_photo、IMAGE/VIDEO テンプレートのヘッダー）には、公開されている https URL が必要です。これらのツールではローカルファイルをアップロードできません。
• テンプレートの更新とプロフィールの変更は審査のため Meta に送信されます。変更がすぐに反映されるかのように伝えず、審査中のステータスを提示してください。

関連スキル

• automation-architecture — WhatsApp が連携するエージェントのワークフロー、ステータス、実行間隔、引き継ぎの構成です。