RabbitDesigns22/whatsapp-number-onboarding: WhatsApp番号オンボーディング（…

WhatsApp番号オンボーディング（Meta Cloud API）

電話番号を接続するのは10クリックのように見えます。実際には、ステップの順序、どのポートフォリオが何を所有しているか、そして「接続済み」と表示されながら何も配信されないMeta画面で失敗します。このスキルは、実際に発生したブロックとその修正方法とともに、安全な順序を提供します。

以下で使用される信頼度タグ: [official] = developers.facebook.com (表内のURL) に記載されているもの; [field] = 実際のオンボーディングで発生し、修正がライブで確認されたもの; [unconfirmed] = 確認されたが、原因や修正が証明されていないもの。[field]または[unconfirmed]をMetaのポリシーとして提示しないでください。

用語: これらの4つを決して混同しないでください

• ビジネスポートフォリオ（Business Manager）: Meta内の会社。
• WhatsApp Business Account (WABA): ポートフォリオ内に存在します。UIでは、メッセージングアカウントIDを使用してください。「WhatsAppアカウント/プレゼンス」IDではありません（後者は「このAPIはサポートされていません」を返します）[field]。
• 電話番号: WABA内に存在します。その電話番号IDは電話番号そのものではありません。
• Metaアプリ: 開発者アカウント内に存在し、ポートフォリオにリンクされています。トークン、アプリシークレット、Webhookを保持します。

制限を述べるときは、それが4つのうちどれに関するものかを言ってください。

計画を決定する制限 [official]

• 新しいポートフォリオは 2つの電話番号 を登録できます。上限は、ビジネスが確認されるか、2,000メッセージの制限に達すると 20 に上がります。
• メッセージング制限は ポートフォリオごとで、そのすべての番号で共有されます: 250 → 2,000 → 10,000 → 100,000 → 無制限。1つのビジーな番号が全員の割り当てを使い果たす可能性があります。
• 登録と登録解除: 番号ごとに72時間あたり10リクエスト ずつ。それを超えると、エラー133016が発生し、番号は72時間ブロックされます。デバッグ中に「有効化」を連打しないでください。
• WhatsApp Managerまたはアプリダッシュボードで番号を追加しても、Cloud APIには登録されません。登録呼び出しは依然として必要です。
• WhatsApp（電話アプリ）ですでに使用されている番号は、そのアカウントが削除されるまで登録できません。
• 番号の削除: ポートフォリオ管理者のみ、API経由では不可、接続されている場合は2段階PINが必要、過去30日間に有料メッセージを送信した場合は不可能。削除は不可逆的として扱ってください。

開始前（一度収集）

ビジネス名（顧客が目にする正確な名前）、法人名、国、完全な住所、電話番号、ウェブサイトまたはFacebookページ、メール、ロゴ、接続する番号。番号にはWhatsAppがインストールされていない必要があります（インストールされている場合は、まずその電話でWhatsAppアカウントを削除してください）。6桁のPINを誰が考案し保持するかを決めてください。

安全な順序（各ステップは確認読み上げで終了）

1. ポートフォリオ (business.facebook.com): 番号を追加する前に、ビジネス情報を完全に入力してください（法人名、住所、電話番号、ウェブサイト）。空の場合、「あなたのビジネスはWhatsAppポリシーを満たしていません」(#2494070) でオンボーディングが失敗しました [field]。
2. WhatsAppアカウント + 番号 (ポートフォリオ設定 → アカウント → WhatsAppアカウント → 追加 → 新しい番号)。表示名 = クライアントのビジネス名。エージェンシーのものではありません。SMS、または固定電話の場合はVOICEで確認します [official]。確認読み上げ: 番号がWABAの下に表示されます。
3. Metaアプリ (developers.facebook.com → アプリ作成 → WhatsAppユースケース)、WABAを所有する同じポートフォリオにリンクします。あるポートフォリオのアプリと別のポートフォリオのWABA: すべてが緑色に表示され、メッセージは配信されませんでした。アプリをWABAのポートフォリオに移動することで修正されました [field]。設定 → 基本: 200を返すプライバシー/利用規約/データ削除URL、カテゴリ、アイコン。
4. システムユーザー そのポートフォリオ内で、アプリとWABAをアセットとして持つもの。トークンには whatsapp_business_messaging + whatsapp_business_management を含め、有効期限はなし。人間がトークンを保存先に貼り付けます。決してエコーしないでください。
5. ID、人が入力するのではなく、あなたが読み取るもの: GET /{waba-id}/phone_numbers → 電話番号ID。電話番号を電話番号ID変数に保存すると、ボットが壊れました [field]。
6. 環境変数 を正確なホスティングプロジェクトに設定します。同じ変数名を持つ複数のクライアントプロジェクト: プロジェクト名を言い、保存する前にタイトルを確認してください。あるクライアントのIDが別のプロジェクトに入り、そのライブボットが間違った番号を指していました [field]。
7. Webhook (アプリ → WhatsApp → 設定): https://<ドメイン>/webhook と検証トークン。messages フィールドを購読してください（常にオンになっているとは限りません）。次に、WABAをアプリに購読させます: POST /{waba-id}/subscribed_apps。
8. 番号を登録: POST /{phone-number-id}/register に6桁のPINを付けます。番号がすでに2段階認証を持っている場合は、既存の PINを使用します [official]。確認読み上げ: GET /{phone-number-id}?fields=status,platform_type,name_status → CONNECTED および CLOUD_API。これ以前は PENDING / NOT_APPLICABLE と表示されます [field]。
9. アプリを公開し、個人の電話から「Hi」を送信して、ボットが応答することを確認します。
10. 請求: テンプレートを送信する前に、WhatsAppアカウントにタイムゾーンと通貨を設定した支払い方法（それ以外の場合は131042） [official]。
11. 最終確認読み上げ: 番号ステータス、GET /{waba-id}/subscribed_apps はこのアプリのみを表示、Webhook URLとフィールド、debug_token は正しいアプリとシステムユーザートークンを表示。

表示名は番号がすでに機能している間、数日間「審査中」のままになることがあります [field]。編集をクリックしないでください。編集すると審査が再開されます。

黄金のルール

• アプリとWABAには同じポートフォリオを使用します。クライアント自身のポートフォリオが審査で止まっている場合、現場でテストされた回避策は、番号を機能しているポートフォリオ（あなたのもの）内のWABAに置き、その同じポートフォリオ内にアプリを置き、2番号の上限内に収めることです [field]。公式の長期的な道は、埋め込みサインアップを備えたテクノロジープロバイダーになることです。
• デフォルトでは、クライアントごとに1つのアプリ。 アプリのコールバックURLがデフォルトの宛先です。MetaはWABA単位および番号単位のWebhookオーバーライドをサポートしています [official] が、テストしていない場合は、クライアントごとに1つのアプリを維持してください。
• ホスティングドメインが変更された場合は、その時点でMetaのWebhookを更新し、確認読み取りを行ってください。ドメインの変更により、ボットが静かに停止しました [field]。
• Cloud APIに残すべき番号に対して、電話にWhatsApp Businessアプリをインストールする「続行」パスを使用しないでください。番号がAPIから外れます [field]。
• 最初に何も壊さないことを試してください。 番号の登録解除、削除、移動は最後の手段であり、Metaがそれを要求する場合のみです（上の制限を参照）。
• ヘルスチェックが緑色なのはMetaがそう言ったときだけです: Metaから電話ステータスを読み取ってください。有効なトークンは番号について何も証明しません [field]。
• ポートフォリオのURLへのリダイレクトは、アセットの所有者を証明しません。 画面上でポートフォリオ名を確認してください [field]。

トラブルシューティング

症状	原因	修正	タグ/ソース
すべて緑色、何も届かない	アプリとWABAが異なるポートフォリオにある	WABAのポートフォリオに新しいアプリを作成し、古いアプリのWebhookを削除	[field]
メッセージが二重に届く / 「app secret mismatch」警告	同じWABAに2つのアプリが登録されている	古いアプリのWebhookとサブスクリプションを削除	[field]
デプロイ後にボットが停止	Webhookが古いドメインのまま	Webhookを更新し、確認読み取りを行う	[field]
クライアントがWABAを共有するときに「No se pudo asignar el socio」（パートナーを割り当てられません）	原因は未証明（新しいか未確認のポートフォリオ、審査中のアカウント）	共有を避ける：1つのポートフォリオで構築する（黄金のルールを参照）	[unconfirmed] 原因、[field] 回避策
開発者オンボーディング中に「ビジネスがWhatsAppポリシーを満たしていません」(#2494070)	不完全なビジネス情報 / 新しいポートフォリオ	ビジネス情報を完了し、代わりにWhatsApp Managerから番号を追加	[field]
WABA IDで「このAPIはサポートされていません」	「WhatsAppアカウント」IDを使用した	メッセージングアカウントIDを使用	[field]
ステータス PENDING、プラットフォーム NOT_APPLICABLE	追加されたが登録されていない	POST /register にPINを付けて実行	[official] + [field]
133005	間違った2段階PIN	番号の既存のPINを使用	エラーコード
133006	番号が確認されていない	SMS/VOICEで確認し、その後登録	エラーコード
133008 / 133009	PIN試行回数が多すぎる/速すぎる	details の時間だけ待機	エラーコード
133010	番号がプラットフォームに登録されていない	登録する	エラーコード
133015	番号が最近削除され、まだ削除中	5分待機	エラーコード
133016	72時間以内に10回以上の登録/登録解除リクエスト	停止し、ブロックが終了するのを待つ	登録
133000	以前の登録解除が失敗した	再度登録解除し、その後登録	エラーコード
「番号はすでにWhatsAppを持っています」	番号がまだ電話アプリまたは別のアカウントにある	最初にそのWhatsAppアカウントを削除	電話番号
テンプレートで131042	支払い方法：クレジットライン、タイムゾーン、または通貨が設定されていない、アカウントが停止されている	WhatsApp Managerで請求を修正し、ユーザーにMetaの error_data.details テキストを表示（推測ではない）	エラーコード
少数の受信者だけで131042	Metaのテキストによればアカウント全体だが、実際のチェックでは18テンプレート中16が配信された	アカウント全体と呼んだり何かを一時停止したりする前に、同じ期間の配信数と失敗数をカウント	[field] ヒューリスティック
131049	「健全なエコシステムエンゲージメントを維持するため」に配信されなかった	再送信する前に少なくとも24時間待つ	エラーコード
131026	受信者が受信できない（WhatsAppがない、古いバージョン、利用規約）	別の方法で連絡	エラーコード
131031	ポリシー違反のためWABAが制限されている	ポリシー施行およびヘルスステータスAPIを参照	エラーコード
クリックしてWhatsApp広告のために番号をFacebookページにリンクできない	表示名がまだ審査中（可能性が高い）	承認を待ち、その後 ページ → リンクされたアカウント → WhatsApp	[unconfirmed]

その他の公式ページ: はじめに · メッセージング制限 · Webhookオーバーライド。

未確認（話題になったらそう言う）

• 「No se pudo asignar el socio」が実際に必要とするもの。
• まったく新しい未確認のポートフォリオがWABAを作成できるかどうか。
• WABA間での番号の移動：Metaのガイドでは、新しいアカウントモデルのアカウントではサポートされていないとされています。現場で完了したことはありません。
• 公式の表示名審査時間。2つの公式URLは2026年11月に404を返しました。

誰が何をするか

エージェントは可能なすべての画面とAPIチェックを実行します。人間は、機械ができないこと（電話からのSMS/音声コード、PIN、シークレットの貼り付け、本人確認、支払い）のみを提供します。