WhatsApp-Nummer gesperrt: Nutzer auf neue Nummer umziehen

Sperrt WhatsApp eine Nummer, ziehen die Chats nicht um: Der Ersatz startet leer und kann niemandem zuerst schreiben. Um deine Nutzer umzuziehen, sagst du es ihnen über einen Kanal, der dir gehört, schickst jedem einen wa.me-Link zur neuen Nummer mit vorausgefüllter Nachricht und erkennst sie wieder, wenn sie schreiben, damit du ihren Verlauf aus deinem eigenen Speicher wiederherstellen kannst.

Was passiert, wenn WhatsApp die Nummer deines Agenten sperrt?

Sperrt WhatsApp eine whasp-Nummer dauerhaft, legt whasp sie still und weist dir kostenlos eine bereite Nummer zu. Der Ersatz hat dasselbe Label, dasselbe Profil (Name, Info-Zeile, Foto) und denselben bezahlten Zeitraum. Sonst wird nichts übertragen. Keine Chats ziehen um, und die neue Nummer hat nichts vom alten Verlauf.

Dein Webhook erhält ein number.replaced-Event mit der alten Nummer und dem Objekt der neuen Nummer, einschließlich ihres wa_link. Hier ist das Event, gekürzt:

{
  "id": "evt_9dK3mQ2vLx",
  "type": "number.replaced",
  "created_at": "2026-10-18T19:00:00Z",
  "data": {
    "old_number": "+15555550100",
    "new_number": {
      "number": "+15555550102",
      "wa_link": "https://wa.me/15555550102",
      "label": "ava",
      "status": "active",
      "profile": { "name": "Ava", "about": "Deine KI-Freundin", "synced": true },
      "paid_until": "2026-11-17T19:00:00Z"
    }
  }
}

Ein number.status_changed-Event kann ebenfalls eintreffen, wenn die Gesundheit der alten Nummer critical wird. Die Reihenfolge der Events ist nicht garantiert, verlass dich also nicht darauf. Die gesperrte Nummer antwortet ab dann niemandem mehr. Warum es passiert ist, liest du unter warum WhatsApp Nummern sperrt. Für die erste Stunde nach einer Sperre, einschließlich WhatsApps eigener Seite zu gesperrten Accounts, siehe was tun, wenn eine Nummer gesperrt ist.

Kann die neue Nummer deinen Nutzern zuerst schreiben?

Die neue Nummer kann niemandem schreiben, der ihr nicht geschrieben hat. Ein Versand an eine solche Person liefert 409 chat_not_open. Das gilt für jede whasp-Nummer, auch für einen Ersatz, und es ist Absicht: Kalte Nachrichten sind es, die persönliche Nummern die Sperre kosten, und eine frische Nummer, die am ersten Tag Hunderte Chats eröffnet, würde die nächste Sperre einladen.

Der Umzug muss also vom Nutzer ausgehen. Er muss auf einen Link tippen und schreiben. Damit ist die Einladung der schwierige Teil, denn sie kann weder aus dem gesperrten WhatsApp-Chat noch von der neuen Nummer kommen. Sie muss über einen Kanal laufen, der dir gehört. Sobald ein Nutzer schreibt, gehen Sendungen ohne from von der neuen Nummer aus, denn die API nutzt die Nummer, der eine Person zuletzt geschrieben hat.

Wie läuft der Umzug der Nutzer ab?

Der Ablauf hat sieben Schritte, und der Code unten deckt die ersten sechs ab.

1. Verifiziere das Event und dedupliziere über seine ID (Events können doppelt ankommen, und die Standard-Webhooks-Spezifikation empfiehlt, webhook-id als Idempotency-Key zu nutzen).
2. Finde die betroffenen Nutzer: die, deren Chat auf old_number lag. Speichere die Nummer bei jedem Nutzer aus message.received, wo message.number dir sagt, welche Nummer die Nachricht bekommen hat.
3. Baue pro Nutzer einen Link: new_number.wa_link plus ?text= (WhatsApps Click-to-Chat-Format) mit einer kurzen Nachricht, die einen einmaligen Code enthält.
4. Schick den Link über deinen eigenen Kanal: ein Banner in der App, eine Push-Benachrichtigung oder eine E-Mail.
5. Lade in Batches ein, die zuletzt aktivsten zuerst.
6. Erkenne die Person wieder, wenn sie schreibt, stelle ihren Verlauf wieder her und lass den Agenten sagen, dass sich die Nummer geändert hat.
7. Erinnere einmal, dann hör auf. Schick nach einer Woche eine einzige Erinnerung an Leute, die nicht zurückgekommen sind. Die übrigen kehren zurück, wenn sie den Agenten wieder brauchen.

Wie verarbeitest du das Event und verschickst die Einladungen?

Verifiziere die Signatur über den Raw Body, dedupliziere über die Event-ID und starte die Einladungen. Dieser Handler nutzt die Prüfung nach Standard Webhooks aus der whasp-Dokumentation wieder.

import { randomBytes } from "node:crypto";
import { Webhook } from "standardwebhooks";

type User = { id: string; phone: string; number: string; lastActive: number; invited?: boolean };

declare const users: Map<string, User>; // deine Datenbank
declare function notify(user: User, link: string): Promise<void>; // E-Mail, Push oder In-App-Banner

const wh = new Webhook(process.env.WHASP_WEBHOOK_SECRET ?? ""); // whsec_...
const seen = new Set<string>(); // bereits verarbeitete Event-IDs
export const codes = new Map<string, string>(); // Einladungscode -> Nutzer-ID
let moveFrom: { number: string; link: string } | null = null;
const DAILY_INVITES = 25; // unter 80 % der 40 neuen Chats pro Tag, mit Platz für Anmeldungen

export async function POST(request: Request) {
  const body = await request.text(); // der Raw Body: erst verifizieren, dann parsen
  let event: any;
  try {
    event = wh.verify(body, Object.fromEntries(request.headers));
  } catch {
    return new Response("Invalid signature", { status: 401 });
  }
  if (seen.has(event.id)) return new Response(null, { status: 204 });
  seen.add(event.id);

  if (event.type === "number.replaced") {
    const { old_number, new_number } = event.data;
    moveFrom = { number: old_number, link: new_number.wa_link };
    await inviteBatch(); // in Produktion: erst mit 2xx antworten, aus einer Queue senden
  }
  return new Response(null, { status: 204 });
}

// Einmal beim Eintreffen des Events ausführen, danach einmal pro Tag, bis niemand mehr übrig ist.
export async function inviteBatch() {
  const target = moveFrom;
  if (!target) return;
  const batch = [...users.values()]
    .filter((u) => u.number === target.number && !u.invited)
    .sort((a, b) => b.lastActive - a.lastActive)
    .slice(0, DAILY_INVITES);
  for (const user of batch) {
    const code = randomBytes(4).toString("hex");
    codes.set(code, user.id);
    const text = encodeURIComponent(`Hallo, ich bin's wieder (Code ${code})`);
    await notify(user, `${target.link}?text=${text}`);
    user.invited = true;
  }
}

Der Code ist zufällig und nur einmal gültig, er ist nicht die Nutzer-ID, denn eine vorausgefüllte Nachricht ist sichtbarer, bearbeitbarer Text, und IDs gehören nicht in Links. Ersetze die Maps und das Set durch Datenbanktabellen.

Die Batch-Größe ergibt sich aus den Limits. Eine whasp-Nummer erlaubt 40 neue Chats pro 24 Stunden und 100 aktive Chats pro 30 Tage, und ihre Gesundheit wird at_risk, wenn ein Limit 80 % überschreitet, das sind 32 neue Chats. Etwa 25 Einladungen pro Tag lassen Platz für neue Anmeldungen. Bei einer Nummer mit 100 aktiven Nutzern dauert es vier Tage, und die zuletzt aktivsten gehen zuerst, denn sie sind es, die es bemerken werden.

Was sollte die Einladung sagen?

Die Einladung sollte sagen, dass der Agent eine neue Nummer hat, zeigen, wohin der Link führt, und klingen wie eine Nachricht von dir, nicht wie eine Warnung. Lass das Wort „gesperrt“ weg; Nutzern ist wichtig, dass Ava umgezogen ist, nicht warum.

Betreff: Ava hat eine neue Nummer

Avas alte WhatsApp-Nummer funktioniert nicht mehr. Tippe unten, um dort weiterzumachen, wo du aufgehört hast. Name und Foto sind dieselben, und sie erinnert sich an alles. [Chat öffnen]

Der Tipp öffnet WhatsApp mit „Hallo, ich bin’s wieder (Code 3f9a1c2e)“ zum Absenden bereit. Schick den Link nur über deine eigene App oder deine eigene Domain. Ein Text von einer unbekannten Nummer, die behauptet, Ava zu sein, wirkt wie Phishing, und die neue Nummer kann ohnehin keinen senden. Zähle nach der ersten Woche drei Dinge: eingeladen, zurückgekehrt und stumm. Die Stummen bekommen eine Erinnerung.

Wie erkennst du einen zurückkehrenden Nutzer und stellst den Verlauf wieder her?

Ordne die Person zuerst über das Telefon und dann über den Code zu und lade das Gespräch dann über deine eigene Nutzer-ID. Die Telefonnummer in chat ist auf der neuen Nummer dieselbe wie auf der alten, ein zurückkehrender Nutzer wird also ohne Code gefunden. Der Code deckt die Person ab, die von einem neuen Telefon schreibt.

declare const users: Map<string, User>;
declare const codes: Map<string, string>;
declare function reply(userId: string, text: string, opts: { moved: boolean }): Promise<void>; // dein Agent: lädt den Verlauf über die Nutzer-ID

export async function onInbound(m: { chat: string; number: string; text: string | null }) {
  const code = m.text?.match(/\(code ([0-9a-f]{8})\)/i)?.[1];
  const byCode = code ? users.get(codes.get(code) ?? "") : undefined;
  const user = byCode ?? [...users.values()].find((u) => u.phone === m.chat);
  if (!user) return; // ein Fremder: auf die Anmeldung verweisen

  if (code) codes.delete(code);
  user.phone = m.chat;
  const moved = user.number !== m.number;
  user.number = m.number; // dieser Chat liegt jetzt auf der neuen Nummer
  // moved: lass den Agenten sagen: "Ich bin's. Meine alte Nummer funktioniert nicht mehr, und ich erinnere mich noch an alles."
  await reply(user.id, m.text ?? "", { moved });
}

Rufe onInbound aus deinem message.received-Handler auf. Die Entwurfsregel dahinter: Verlauf nach Nutzer ordnen, nie nach Nummer. Wenn deine Gedächtnistabelle die whasp-Nummer als Teil des Schlüssels nutzt, verwaist eine Sperre jedes Gespräch. Gesprächsgedächtnis zeigt ein Schema, das einen Umzug übersteht.

Sag der Person, was passiert ist. Ein Agent, der einen zurückkehrenden Nutzer mit seinem Onboarding-Skript begrüßt, wirkt wie ein Fremder. Eine Zeile genügt: Es ist derselbe Agent, die alte Nummer funktioniert nicht mehr, und das Gespräch geht weiter.

Was, wenn ein Nutzer keinen anderen Kanal hat?

Ist WhatsApp dein einziger Kanal zu einem Nutzer, erreichst du ihn nicht. Der alte Chat ist stumm, und die neue Nummer kann nicht zuerst schreiben. Drei Gewohnheiten verkleinern diese Lücke.

Erfasse bei der Anmeldung einen zweiten Kanal. Eine E-Mail-Adresse oder ein App-Login kostet ein Feld. Es ist der einzige verlässliche Weg zurück.

Veröffentliche einen stabilen Link. Setze auf deiner eigenen Domain eine Weiterleitung auf, die im Moment des Klicks mit GET /v1/numbers/pick nach einer gesunden Nummer fragt. Nutze diesen Link dort, wo er dauerhaft halten muss, etwa in deiner App, in Bios und auf QR-Codes, statt eines rohen wa.me-Links.

// GET https://chat.example.com/ava: der eine Link, den du druckst, postest und in E-Mails setzt.
export async function GET() {
  const res = await fetch(
    `https://api.whasp.ai/v1/numbers/pick?text=${encodeURIComponent("Hallo, ich bin's")}`,
    { headers: { Authorization: `Bearer ${process.env.WHASP_API_KEY}` } },
  );
  if (!res.ok) return new Response("Versuch es in einer Minute noch einmal.", { status: 503 }); // 409 no_capacity
  const { wa_link } = await res.json();
  return Response.redirect(wa_link, 302);
}

Setze diesen Link ins Profil. Ein Ersatz behält das Profil, und die Info-Zeile erlaubt vorerst bis zu 139 Zeichen einfaches ASCII. Eine kurze URL dort reist zu jedem künftigen Ersatz mit und steht dort, wo Nutzer sie lesen können. wa.me-Links und QR-Codes behandelt die Platzierung.

Was solltest du vor der ersten Sperre einrichten?

Jede Nummer, die wie ein Mensch bedient wird, kann gesperrt werden, bereite dich also vor, solange es ruhig ist.

• Teste den Handler mit einem Beispiel-Payload für number.replaced, einschließlich eines Duplikats und einer ungültigen Signatur.
• Plane für ein verpasstes Event. whasp wiederholt eine Zustellung bis zu 12-mal mit Backoff, gibt dann auf und verwirft den Body, er kann also nicht erneut gesendet werden. GET /v1/webhook/deliveries listet die letzten 7 Tage auf. GET /v1/numbers listet deine Nummern auf: Eine, die du nicht kennst, ist der Ersatz, und die Felder status und replaced_by zeigen, was mit der alten passiert ist.
• Betreibe mehr als eine Nummer, wenn du kannst. Eine Sperre betrifft dann nur die Nutzer auf dieser Nummer. Wie viele Nummern dein Agent braucht enthält die Rechnung.
• Ordne den Verlauf nach Nutzer, und halte auf jedem Nutzerdatensatz eine Telefonnummer.

Was solltest du als Nächstes tun?

Baue diese Woche den number.replaced-Handler ein und setze dann den stabilen Link in deine App und in die Info-Zeile des Profils. Erfasse ab jetzt bei der Anmeldung eine E-Mail-Adresse. Die vollständige API steht in der Dokumentation.