WhatsApp-Nummern-Onboarding (Meta Cloud API)

Was macht WhatsApp-Nummern-Onboarding (Meta Cloud API)?

Das Verbinden einer Nummer sieht aus wie 10 Klicks. In der Praxis scheitert es an der Reihenfolge der Schritte, daran, welches Portfolio was besitzt, und an Meta-Bildschirmen, die „verbunden“ anzeigen, während nichts ankommt. Dieses Skill liefert die sichere Reihenfolge plus die Blockaden, die tatsächlich aufgetreten sind, mit ihren Lösungen.

Vertrauenswürdigkeit der Markierungen: [official] = auf developers.facebook.com beschrieben (URL in der Tabelle); [field] = in echten Onboardings aufgetreten und live bestätigt; [unconfirmed] = gesehen, Ursache oder Lösung nie bewiesen. [field] oder [unconfirmed] niemals als Meta-Richtlinie darstellen.

Begriffe: Diese vier niemals verwechseln

• Business Portfolio (Business Manager) : Das Unternehmen bei Meta.
• WhatsApp Business Account (WABA) : Lebt innerhalb eines Portfolios. In der UI die Messaging-Account-ID verwenden, nicht die „WhatsApp-Konto-/Präsenz-ID“ (letztere gibt „This API is not supported“ zurück) [field].
• Telefonnummer : Lebt innerhalb einer WABA. Ihre Telefonnummer-ID ist nicht die Telefonnummer.
• Meta-App : Lebt in einem Entwicklerkonto und ist mit einem Portfolio verknüpft; sie enthält den Token, das App-Geheimnis und den Webhook.

Wenn Sie ein Limit nennen, sagen Sie, um welches der vier es sich handelt.

Limits, die den Plan bestimmen [official]

• Ein neues Portfolio kann 2 Telefonnummern registrieren; das Limit steigt auf 20, wenn das Unternehmen verifiziert ist oder das 2.000-Nachrichten-Limit erreicht hat.
• Nachrichtenlimits gelten pro Portfolio, geteilt von allen seinen Nummern: 250 → 2.000 → 10.000 → 100.000 → unbegrenzt. Eine stark genutzte Nummer kann das gesamte Kontingent aufbrauchen.
• Registrieren und Deregistrieren: 10 Anfragen pro Nummer pro 72 h; danach Fehler 133016 und die Nummer ist für 72 h gesperrt. „Aktivieren“ während der Fehlersuche nicht mehrfach drücken.
• Das Hinzufügen einer Nummer im WhatsApp Manager oder im App-Dashboard registriert sie nicht für die Cloud API; der Register-Aufruf ist dennoch erforderlich.
• Eine Nummer, die bereits mit WhatsApp (Telefon-App) genutzt wird, kann erst registriert werden, wenn dieses Konto gelöscht ist.
• Löschen einer Nummer: Nur Portfolio-Admins, nicht per API, benötigt die 2-Schritt-PIN, falls verbunden, und ist unmöglich, wenn in den letzten 30 Tagen kostenpflichtige Nachrichten gesendet wurden. Löschen als irreversibel behandeln.

Vor dem Start (einmal sammeln)

Geschäftsname, genau wie Kunden ihn sehen werden, Rechtsform, Land, vollständige Adresse, Telefon, Website oder Facebook-Seite, E-Mail, Logo und die zu verbindende Nummer. Die Nummer darf WhatsApp nicht installiert haben (falls doch, zuerst das WhatsApp-Konto auf dem Telefon löschen). Entscheiden, wer die 6-stellige PIN erfindet und verwahrt.

Sichere Reihenfolge (jeder Schritt endet mit einer Rückleseprüfung)

1. Portfolio (business.facebook.com): Geschäftsinformationen vollständig ausfüllen (Rechtsform, Adresse, Telefon, Website) bevor eine Nummer hinzugefügt wird. Bei leerem Feld schlug das Onboarding mit „Ihr Unternehmen erfüllt nicht die WhatsApp-Richtlinien“ fehl (#2494070) [field].
2. WhatsApp-Konto + Nummer (Portfolio-Einstellungen → Konten → WhatsApp-Konten → Hinzufügen → neue Nummer). Anzeigename = der Geschäftsname des Kunden, niemals der der Agentur. Per SMS oder VOICE für Festnetz verifizieren [official]. Rückleseprüfung: Die Nummer erscheint unter der WABA.
3. Meta-App (developers.facebook.com → App erstellen → WhatsApp-Anwendungsfall), verknüpft mit demselben Portfolio, das die WABA besitzt. App in einem Portfolio und WABA in einem anderen: Alles zeigte grün, aber keine Nachricht wurde zugestellt; das Verschieben der App in das Portfolio der WABA behob das Problem [field]. Einstellungen → Basis: Datenschutz-/AGB-/Datenlöschungs-URLs, die 200 zurückgeben, Kategorie, Symbol.
4. Systembenutzer in diesem Portfolio mit der App und der WABA als Ressourcen; Token mit whatsapp_business_messaging + whatsapp_business_management, ohne Ablauf. Ein Mensch fügt den Token dort ein, wo er gespeichert wird; niemals ausgeben.
5. IDs, von Ihnen ausgelesen, nicht von einer Person eingegeben: GET /{waba-id}/phone_numbers → Telefonnummer-ID. Das Speichern der Telefonnummer in der Telefonnummer-ID-Variable hat einen Bot beschädigt [field].
6. Umgebungsvariablen im genauen Hosting-Projekt. Mehrere Kundenprojekte mit denselben Variablennamen: Projekttitel nennen und vor dem Speichern prüfen. IDs eines Kunden gelangten in das Projekt eines anderen und dessen Live-Bot zeigte auf die falsche Nummer [field].
7. Webhook (App → WhatsApp → Konfiguration): https://<domain>/webhook plus Verify-Token; das messages-Feld abonnieren (ist nicht immer aktiviert). Dann die WABA mit der App abonnieren: POST /{waba-id}/subscribed_apps.
8. Nummer registrieren: POST /{phone-number-id}/register mit der 6-stelligen PIN. Wenn die Nummer bereits eine 2-Schritt-Verifizierung hat, die bestehende PIN verwenden [official]. Rückleseprüfung: GET /{phone-number-id}?fields=status,platform_type,name_status → CONNECTED und CLOUD_API. Zuvor zeigt es PENDING / NOT_APPLICABLE [field].
9. App veröffentlichen, dann von einem persönlichen Telefon aus „Hallo“ senden und sehen, ob der Bot antwortet.
10. Abrechnung: Zahlungsmethode, Zeitzone und Währung im WhatsApp-Konto einstellen, bevor Vorlagen gesendet werden (sonst 131042) [official].
11. Abschließende Rückleseprüfung: Nummernstatus, GET /{waba-id}/subscribed_apps zeigt nur diese App, Webhook-URL und -Felder, debug_token zeigt die richtige App und einen Systembenutzer-Token.

Der Anzeigename kann tagelang „in Prüfung“ bleiben, während die Nummer bereits funktioniert [field]; nicht auf „Bearbeiten“ klicken, da eine Bearbeitung die Prüfung neu startet.

Goldene Regeln

• Gleiches Portfolio für die App und die WABA. Wenn das eigene Portfolio des Kunden in der Prüfung feststeckt, besteht ein feldgetesteter Ausweg darin, die Nummer in eine WABA in einem funktionierenden Portfolio (Ihrem) zu legen, mit der App im selben Portfolio, innerhalb des 2-Nummern-Limits [field]. Der offizielle langfristige Weg ist die Zertifizierung als Technologieanbieter mit Embedded Signup.
• Standardmäßig eine App pro Kunde. Die Callback-URL der App ist das Standardziel. Meta unterstützt pro-WABA- und pro-Nummer-Webhook-Überschreibungen [official], aber wenn Sie diese nicht getestet haben, behalten Sie eine App pro Kunde.
• Wenn sich die Hosting-Domain ändert, aktualisieren Sie sofort den Webhook in Meta und lesen Sie ihn zurück. Eine Domain-Änderung hat einen Bot lautlos gestoppt [field].
• Niemals den Pfad „Weiter“ verwenden, der die WhatsApp Business App auf dem Telefon installiert, für eine Nummer, die auf der Cloud API bleiben soll: Es entfernt die Nummer von der API [field].
• Zuerst versuchen, was nichts kaputt macht. Deregistrieren, Löschen oder Verschieben einer Nummer kommen zuletzt, nur wenn Meta es verlangt (siehe Limits oben).
• Ein Gesundheitscheck ist nur dann grün, wenn Meta das sagt: Den Telefonstatus von Meta auslesen. Ein gültiger Token beweist nichts über die Nummer [field].
• Eine Weiterleitung zur URL eines Portfolios beweist nicht, wem eine Ressource gehört. Den Portfolionamen auf dem Bildschirm bestätigen [field].

Fehlerbehebung

Symptom	Ursache	Lösung	Markierung / Quelle
Alles grün, nichts kommt an	App und WABA in verschiedenen Portfolios	Neue App im Portfolio der WABA; Webhook der alten App entfernen	[field]
Nachrichten kommen doppelt / Warnungen „app secret mismatch“	Zwei Apps haben die gleiche WABA abonniert	Webhook und Abonnement der alten App entfernen	[field]
Bot nach Deployment gestoppt	Webhook noch auf alter Domain	Webhook aktualisieren und zurücklesen	[field]
„No se pudo asignar el socio“ (Partner zuweisen) wenn der Kunde seine WABA teilt	Nie bewiesen (neues oder nicht verifiziertes Portfolio, Konto in Prüfung)	Teilen vermeiden: In einem Portfolio bauen (siehe goldene Regeln)	[unconfirmed] Ursache, [field] Workaround
„Unternehmen erfüllt nicht die WhatsApp-Richtlinien“ (#2494070) während des Entwickler-Onboardings	Unvollständige Geschäftsinformationen / neues Portfolio	Geschäftsinformationen vervollständigen; Nummer stattdessen über WhatsApp Manager hinzufügen	[field]
„This API is not supported“ mit der WABA-ID	„WhatsApp-Konto“-ID verwendet	Messaging-Account-ID verwenden	[field]
Status PENDING, Plattform NOT_APPLICABLE	Hinzugefügt, aber nicht registriert	POST /register mit PIN	[official] + [field]
133005	Falsche 2-Schritt-PIN	Bestehende PIN der Nummer verwenden	Fehlercodes
133006	Nummer nicht verifiziert	Per SMS/VOICE verifizieren, dann registrieren	Fehlercodes
133008 / 133009	Zu viele oder zu schnelle PIN-Versuche	Zeit in details abwarten	Fehlercodes
133010	Nummer nicht auf der Plattform registriert	Registrieren	Fehlercodes
133015	Nummer kürzlich gelöscht, wird noch gelöscht	5 Minuten warten	Fehlercodes
133016	Über 10 Registrierungs-/Deregistrierungsanfragen in 72 h	Stoppen; auf Ende der Sperre warten	Registrierung
133000	Eine vorherige Deregistrierung ist fehlgeschlagen	Erneut deregistrieren, dann registrieren	Fehlercodes
„Nummer hat bereits WhatsApp“	Nummer noch in der Telefon-App oder einem anderen Konto	Zuerst dieses WhatsApp-Konto löschen	Telefonnummern
131042 bei Vorlagen	Zahlungsmethode: Kreditlinie, Zeitzone oder Währung nicht gesetzt, Konto gesperrt	Abrechnung im WhatsApp Manager korrigieren; dem Benutzer den Text von Metas error_data.details zeigen, keine Vermutung	Fehlercodes
131042 nur bei wenigen Empfängern	Konto-weit laut Meta-Text, dennoch wurden in einem Live-Check 16 von 18 Vorlagen zugestellt	Zustellungen vs. Fehlschläge im gleichen Zeitraum zählen bevor es als konto-weit bezeichnet oder etwas pausiert wird	[field] Heuristik
131049	Nicht zugestellt „zur Aufrechterhaltung eines gesunden Ökosystem-Engagements“	Mindestens 24 h vor erneuten Senden warten	Fehlercodes
131026	Empfänger kann nicht empfangen (kein WhatsApp, alte Version, AGB)	Auf anderem Weg kontaktieren	Fehlercodes
131031	WABA wegen Richtlinienverstoß eingeschränkt	Siehe Richtliniendurchsetzung und Health Status API	Fehlercodes
Nummer kann nicht mit der Facebook-Seite für Click-to-WhatsApp-Anzeigen verknüpft werden	Anzeigename noch in Prüfung (wahrscheinlich)	Auf Genehmigung warten, dann Seite → Verknüpfte Konten → WhatsApp	[unconfirmed]

Weitere offizielle Seiten: Erste Schritte · Nachrichtenlimits · Webhook-Überschreibungen.

Nicht verifiziert (sagen, wenn es auftaucht)

• Was „No se pudo asignar el socio“ wirklich erfordert.
• Ob ein brandneues, nicht verifiziertes Portfolio überhaupt eine WABA erstellen darf.
• Verschieben einer Nummer zwischen WABAs: Metas Anleitung sagt, es wird für Konten im neuen Kontomodell nicht unterstützt; es wurde nie in der Praxis abgeschlossen.
• Offizielle Prüfzeiten für Anzeigenamen. Die beiden offiziellen URLs gaben im November 2026 einen 404 zurück.

Wer macht was

Der Agent führt jede Bildschirm- und API-Prüfung durch, die möglich ist. Die Person stellt nur das zur Verfügung, was eine Maschine nicht kann: den SMS/Sprachcode vom Telefon, die PIN, das Einfügen von Geheimnissen, Identitätsprüfungen, Zahlungen.