WhatsApp-Link erstellen: wa.me und QR-Code für KI-Agenten

Ein wa.me-Link ist die Click-to-Chat-URL von WhatsApp. Das Format ist https://wa.me/<nummer>, wobei die Nummer im vollständigen internationalen Format steht, ohne Pluszeichen, Nullen, Klammern oder Bindestriche, und ?text= eine URL-codierte erste Nachricht anhängt. Ein Tipp auf den Link öffnet einen Chat mit der Nummer deines Agenten, der Nutzer schreibt also zuerst, und dein Agent kann antworten.

Wie sieht das genaue Format eines wa.me-Links aus?

Die Hilfeseite zu Click to Chat von WhatsApp dokumentiert drei Formen:

https://wa.me/15555550100
https://wa.me/15555550100?text=Hallo%20Ava
https://wa.me/?text=Hallo%20Ava

Der erste Link öffnet einen Chat mit dieser Nummer. Der zweite legt zusätzlich den Text in das Nachrichtenfeld. Der dritte hat keine Nummer: WhatsApp zeigt eine Kontaktliste, an die die Nachricht gehen soll. Er dient also zum Teilen und nicht dazu, einen Chat mit deinem Agenten zu starten.

Die Regel zur Nummer lautet auf dieser Seite „eine vollständige Telefonnummer im internationalen Format“ (Übersetzung von uns), ohne Nullen, Klammern oder Bindestriche. Als Beispiel für das, was du nicht verwenden sollst, nennt sie https://wa.me/+001-(XXX)XXXXXXX. whasp liefert Nummern im E.164-Format (+15555550100), lass also das Pluszeichen weg.

Drei Verhaltensweisen, die du kennen solltest:

• Der Link funktioniert auf Smartphones und in WhatsApp Web.
• Er funktioniert auch für eine Nummer, die nicht im Adressbuch des Nutzers steht, solange die Nummer einen aktiven WhatsApp-Account hat.
• Der vorausgefüllte Text landet im Textfeld. Er wird nicht gesendet. Der Nutzer tippt auf Senden und kann den Text vorher ändern oder löschen.

Wie baust du den Link im Code?

Entferne aus der E.164-Nummer alle Zeichen außer Ziffern und codiere danach den Text per URL-Encoding. Füge Rohtext nie direkt in die URL ein: Ein & beendet den Parameter vorzeitig, und ein # beginnt ein Fragment. encodeURIComponent erledigt beides.

export function waLink(e164: string, text?: string): string {
  const digits = e164.replace(/\D/g, "").replace(/^0+/, ""); // "+1 555 555 0100" -> "15555550100"
  return `https://wa.me/${digits}` + (text ? `?text=${encodeURIComponent(text)}` : "");
}

Vier Fehler, die du vermeiden solltest:

• Pluszeichen, eine führende 00 oder Leerzeichen in der Nummer stehen lassen. Die Seite von WhatsApp sagt, dass sie wegfallen.
• Das Encoding weglassen, sodass ein & in der Nachricht den Text abschneidet.
• Den Link einmal bauen und zwischenspeichern. Nummern laufen voll und werden ersetzt.
• Die vorausgefüllte Nachricht für gesendet halten. Sie steht im Textfeld, bis der Nutzer auf Senden tippt.

Halte den vorausgefüllten Text kurz und schlicht. Die Seite von WhatsApp nennt dafür keine Längengrenze, aber Meta begrenzt vorausgefüllten Text bei den eigenen QR-Codes und Kurzlinks auf 140 Zeichen, eine sinnvolle Obergrenze für jede Einstiegsnachricht.

Verzichte in diesem Text auf Emoji. Am 19. Oktober 2026 haben wir wa.me-Links mit Emoji in ?text= abgerufen, und die Weiterleitung auf api.whatsapp.com/send lieferte statt des Emoji das Unicode-Ersatzzeichen (%EF%BF%BD). Lateinische Buchstaben mit Akzent kamen unverändert an, und derselbe Text direkt an api.whatsapp.com/send behielt das Emoji. Du kannst die Prüfung wiederholen:

curl -sI "https://wa.me/15555550100?text=Hi%20%F0%9F%91%8B" | grep -i location

WhatsApp kann das ändern, teste also auf echten Smartphones, bevor du dich auf eines der beiden Verhalten verlässt.

Wie erstellst du einen QR-Code für einen wa.me-Link?

Ein QR-Code für Click to Chat ist der Link selbst, codiert. Erzeuge ihn mit einer beliebigen QR-Bibliothek aus der vollständigen URL und zeige ihn auf Desktop-Seiten, wo der Nutzer kein Smartphone in der Hand hält. Eine Smartphone-Kamera liest einen QR-Code mit einer URL und bietet an, sie zu öffnen, und wa.me übergibt den Chat dann an WhatsApp. Metas Dokumentation beschreibt für die eigenen QR-Codes denselben Ablauf mit dem Scannen per Kamera.

import QRCode from "qrcode";

const link = waLink("+15555550100", "Hallo Ava");
const svg = await QRCode.toString(link, { type: "svg", margin: 2, errorCorrectionLevel: "M" });
await QRCode.toFile("ava.png", link, { width: 512, margin: 2 });

Das ist das Paket qrcode. Nimm das SVG für den Druck, weil es ohne Unschärfe skaliert (Metas Dokumentation zu QR-Codes empfiehlt dasselbe), und das PNG für Bildschirme. Eine kürzere URL ergibt einen einfacheren Code, der sich leichter scannen lässt. Teste den gedruckten Code in seiner endgültigen Größe auf zwei oder drei verschiedenen Smartphones, bevor du tausend Aufkleber bestellst.

Verwechsle das nicht mit Metas eigenen QR-Codes und Kurzlinks. Diese Funktion gehört zur WhatsApp Business Platform: bis zu 2.000 pro Business-Telefonnummer, vorausgefüllter Text bis 140 Zeichen, keine Scan-Statistiken, verwaltet über die Business Management API. Eine whasp-Nummer ist ein persönlicher WhatsApp-Account, du verwendest also einfache wa.me-Links.

Woher weiß dein Agent, wer gerade geschrieben hat?

Ein message.received-Event enthält die Telefonnummer des Absenders (chat), seinen WhatsApp-Namen (sender_name) und den Text. Deine Nutzer-ID enthält es nicht. Hat die Person in deiner App auf einen Button geklickt, willst du beides verknüpfen. Setze dazu einen einmaligen Code in den vorausgefüllten Text.

import { randomBytes } from "node:crypto";

const API = "https://api.whasp.ai/v1";
const pending = new Map<string, { userId: string; expires: number }>(); // nimm deine Datenbank

export async function startChat(userId: string) {
  const code = randomBytes(3).toString("hex"); // z. B. "9f3a1c"
  pending.set(code, { userId, expires: Date.now() + 24 * 60 * 60 * 1000 });

  const text = `Hallo Ava, mein Code ist ${code}`;
  const res = await fetch(`${API}/numbers/pick?text=${encodeURIComponent(text)}`, {
    headers: { Authorization: `Bearer ${process.env.WHASP_API_KEY}` },
  });
  if (res.status === 409) return null; // no_capacity: jede Nummer ist voll, offline oder nicht gesund
  if (!res.ok) throw new Error(`whasp answered ${res.status}`);
  return (await res.json()) as { number: string; wa_link: string };
}

// In deinem message.received-Handler: wer ist das?
export function claimCode(text: string): string | null {
  const code = /mein code ist ([0-9a-f]{6})\b/i.exec(text)?.[1]?.toLowerCase();
  const hit = code ? pending.get(code) : undefined;
  if (!code || !hit || hit.expires < Date.now()) return null;
  pending.delete(code); // einmal verwendbar
  return hit.userId;
}

Gibt claimCode eine Nutzer-ID zurück, speichere das Paar: den chat des Absenders, die number, die die Nachricht erhalten hat, und deinen Nutzer. Ab da ordnest du die Person über die Telefonnummer zu. Die Verarbeitung des Webhooks selbst (Signaturprüfung, Deduplizierung über die Event-ID) steht in WhatsApp-Webhooks verarbeiten: Signatur, Retries, Duplikate.

Der Code ist eine Behauptung, kein Beweis. Der Nutzer kann den Text ändern, und jeder, der den Link bekommt, kann ihn absenden. Mach den Code einmalig verwendbar und kurzlebig, wähle ihn so, dass er nichts verrät (nie eine E-Mail-Adresse oder ein Token), und schreibe nie ein Geheimnis in einen Link, der im Browserverlauf und in einem Chat landet.

Wie wählt whasp die Nummer im Link aus?

GET /v1/numbers/pick von whasp liefert die gesunde, online befindliche Nummer mit dem meisten Platz für einen neuen Nutzer, dazu einen wa_link mit deinem vorausgefüllten text. Die Antwort ist 409 no_capacity, wenn jede Nummer voll, offline oder nicht gesund ist. Eine Nummer nimmt bis zu 100 aktive Chats in 30 Tagen und 40 neue Chats in 24 Stunden auf, danach fällt sie aus pick heraus (eingehende Nachrichten kommen weiterhin an). Rufe pick auf, wenn der Nutzer den Chat anfordert, nicht beim Build und nicht einmal für eine ganze Kampagne.

Wiederkehrende Nutzer sollten zur selben Nummer zurückgehen. Das message.received-Event enthält die number, die es empfangen hat, und ein Versand ohne from geht von der Nummer aus, an die die Person zuletzt geschrieben hat. Speichere sie beim Nutzer und baue den nächsten Link mit waLink(number, text).

Nummern ändern sich auch. Sperrt WhatsApp eine, nimmt whasp sie außer Betrieb und gibt dir eine Ersatznummer. Die Chats ziehen nicht um, und die neue Nummer kann nicht zuerst schreiben, ein Link auf die alte Nummer ist also tot. Erzeuge Links bei Bedarf und lies WhatsApp-Nummer gesperrt: Nutzer auf neue Nummer umziehen für das ganze Vorgehen. Wie viele WhatsApp-Nummern braucht dein KI-Agent? behandelt die Kapazität.

Warum hilft es, dass Nutzer zuerst schreiben?

Eine whasp-Nummer kann keinen Chat eröffnen: Ein Versand an jemanden, der nie geschrieben hat, liefert 409 chat_not_open. Link und QR-Code sind die Eingangstür. Sie halten die Nummer außerdem gesund. Entwickler, die inoffizielle Bibliotheken nutzen, melden seit mindestens März 2026 den Fehler 463, den „Reachout-Timelock“, und die gängige Theorie bringt ihn mit Nachrichten an Leute in Verbindung, die nie selbst geschrieben haben. WhatsApp-Fehler 463 und der Reachout-Timelock trennt Bestätigtes von Theorie. Bei Click to Chat beginnt jede Unterhaltung mit einer eingehenden Nachricht, und eine vorausgefüllte Nachricht gibt deinem Agenten sofort seine erste Eingabe.

Wohin gehören der Link und der QR-Code?

Für die letzten beiden Zeilen zeigst du auf eine Weiterleitung auf deiner eigenen Domain, die bei whasp eine frische Nummer abfragt und den Besucher weiterschickt:

import { createServer } from "node:http";

createServer(async (req, res) => {
  if (req.url !== "/chat") return void res.writeHead(404).end();
  const pick = await fetch(`https://api.whasp.ai/v1/numbers/pick?text=${encodeURIComponent("Hallo Ava")}`, {
    headers: { Authorization: `Bearer ${process.env.WHASP_API_KEY}` },
  });
  if (pick.ok) {
    const { wa_link } = (await pick.json()) as { wa_link: string };
    res.writeHead(302, { Location: wa_link }).end();
  } else {
    res.writeHead(503).end("Alle unsere Nummern sind gerade belegt. Versuch es in ein paar Minuten noch einmal.");
  }
}).listen(3000);

Ein anonymer Besucher hat keinen Code, lass den Agenten also fragen, was er braucht, sobald der Chat offen ist. Bei einem bekannten Nutzer, etwa in der Zeile mit der E-Mail, lass die Weiterleitung startChat(userId) aus dem vorigen Abschnitt aufrufen, statt einen festen Text zu verwenden. WhatsApp bietet außerdem einen offiziellen Button „Chat on WhatsApp“ in Grün und Weiß an, und seine Hilfeseite sagt, man solle ihn unverändert verwenden.

Was du als Nächstes tun kannst

Lege im Dashboard eine Nummer an und folge dann dem Quickstart, um das erste message.received-Event zu empfangen. Baue die Weiterleitung von oben in deine Seite ein, hänge ihre URL hinter einen Button und einen QR-Code und prüfe den ganzen Weg auf einem iPhone und einem Android-Telefon. Wenn du einen Begleiter baust, zeigt KI-Begleiter auf WhatsApp starten: Anleitung für 2026, wo dieser Link im Onboarding passt.