Webhook verbinden und testen

Über den Webhook liefert Meta eingehende Nachrichten an SwissMentor. Die Zieladresse muss öffentlich über HTTPS erreichbar sein und darf keine vorgeschaltete Anmeldung verlangen. Die SwissMentor-Konfiguration und die Zugangsdaten müssen vorher aktiviert sein.

Die richtige Meta-Oberfläche öffnen

Unter Business-Einstellungen → Konten → WhatsApp-Konten verwalten Sie den Zugriff auf das WhatsApp-Konto. Der dortige Reiter Conversation routing gehört zur Weiterleitung zwischen Antwortsystemen. Die Callback-Adresse tragen Sie im Developer-Dashboard der Meta-App ein.

Öffnen Sie die Startseite von Meta for Developers, melden Sie sich bei Bedarf über Login an und wählen Sie My Apps. Öffnen Sie die für SwissMentor erstellte App. Im App-Dashboard öffnen Sie Use cases → Connect with customers through WhatsApp → Customize → Configuration. Der deutschsprachige WhatsApp-Anwendungsfall heisst Über WhatsApp mit deinen Kunden in Kontakt treten. Die Position von Configuration im WhatsApp-Anwendungsfall ist im Einrichtungsleitfaden mit Meta-Masken beschrieben.

Vorgehen

Lassen Sie sich von der technischen Administration die öffentlich erreichbare API-Adresse dieser SwissMentor-Umgebung geben. Die Callback-Adresse hat diese Form:
```
https://<api-host>/webhook/whatsapp
```
Ersetzen Sie <api-host> durch den tatsächlichen öffentlichen API-Host. Die Adresse endet mit whatsapp, ohne Punkt. Öffnen Sie sie zum Prüfen in einem privaten Browserfenster ohne Anmeldung. Eine Weiterleitung zur Coder-Anmeldung muss vor dem Bestätigen in Meta behoben werden. Die Weboberfläche auf Port 4200 ist in Coder kein Webhook-Zugang.
Öffnen Sie das Developer-Dashboard der Meta-App und deren WhatsApp-Konfiguration wie oben beschrieben.
Öffnen Sie Configuration und die Webhooks-Konfiguration. Tragen Sie die Callback-Adresse und denselben Verify token ein, den Sie in SwissMentor unter Webhook Verify-Token gespeichert haben.
Klicken Sie auf Verify and save. Meta muss die Adresse erfolgreich bestätigen. Speichern allein beweist noch keinen Empfang von Schülernachrichten.
Aktivieren Sie in den Webhook-Feldern das Abonnement messages. Es liefert eingehende Nachrichten und Nachrichtenstatus. Falls Meta getrennt nach Objekt und Feld fragt, verwenden Sie das WhatsApp-Business-Konto und dort das Feld messages.
Prüfen Sie vor dem Transporttest den Nummernstatus CONNECTED. Falls noch PENDING angezeigt wird, schliessen Sie zuerst die Cloud-API-Registrierung der Nummer ab. Führen Sie anschliessend den Transporttest durch: Senden Sie von Ihrer eigenen WhatsApp-Nummer Hallo an die eingerichtete Schulnummer. SwissMentor muss mit einer KI-Antwort reagieren. Fragen Sie anschliessend «Welche Kurse bietet ihr an?». Der Bot verwendet dafür ausschliesslich das öffentlich ausgeschriebene Kursangebot. Allgemeine Fragen brauchen keine Kontoverbindung.
Für den zusätzlichen Test persönlicher Auskünfte melden Sie sich mit dem vorgesehenen Schülerkonto in SwissMentor an und öffnen Sie Einstellungen → WhatsApp. Ein Administratorkonto ist für die Schüler-Verknüpfung nicht zugelassen.
Wählen Sie WhatsApp verbinden, öffnen Sie den erzeugten Link und senden Sie in WhatsApp die vorbereitete Nachricht unverändert an die Schulnummer. Der Link ist 15 Minuten gültig und kann nur einmal eingelöst werden.
Warten Sie auf die Bestätigung im WhatsApp-Chat. Fragen Sie danach beispielsweise «Welche Kurse besuche ich?». Die Antwort muss zu diesem Schülerkonto gehören. In SwissMentor können Sie Verbindungsstatus aktualisieren wählen.
Senden Sie STOP. SwissMentor bestätigt die Trennung. Eine anschliessende persönliche Frage darf erst nach einer erneuten Verknüpfung beantwortet werden. Allgemeine Kursfragen müssen weiterhin ohne Verbindung funktionieren.

Meta beschreibt die Bestätigung und den Nachrichtenempfang in seiner Webhook-Dokumentation. Die Verarbeitung und Zeitgrenzen des WhatsApp-Bots entsprechen der aktuellen SwissMentor-Implementierung.

Coder-Umgebung

Der Coder-Link zur Weboberfläche ist nicht automatisch die Callback-Adresse. Der Web-Entwicklungsserver reicht /webhook/whatsapp derzeit nicht an die API weiter. Verwenden Sie einen HTTPS-Zugang zur API. Ein Coder-Zugang, der erst auf die Coder-Anmeldung umleitet, ist für Meta nicht verwendbar. Die technische Administration muss einen gezielt freigegebenen Webhook-Zugang bereitstellen.

Ein Aufruf der Callback-Adresse ohne Meta-Parameter darf bei SwissMentor 403 Forbidden liefern. Das ist etwas anderes als eine Weiterleitung zur Anmeldung, 404 oder 502. Die eigentliche Bestätigung erfolgt mit Verify and save und dem passenden Token.

Wenn der Test scheitert

Beobachtung	Nächste Prüfung
Verify and save scheitert	Stimmt die API-Adresse? Ist sie ohne Anmeldung erreichbar? Sind WhatsApp Integration aktiv und der Verify-Token bereits geladen?
Verbindungsnachricht kommt in WhatsApp an, SwissMentor antwortet nicht	Abonnement messages, zugeordnete App, Phone number ID sowie laufenden Worker prüfen. Die technische Administration prüft den gespeicherten Eingang und den Worker-Lauf.
Kein gültiger Verbindungslink	Schulnummer und Bot-Schalter prüfen. Das Konto muss für die Portal-Anmeldung zugelassen sein.
Verbindungscode ungültig oder abgelaufen	In den Einstellungen einen neuen Link erzeugen und dessen vorbereitete Nachricht innerhalb von 15 Minuten senden.
Nur die allgemeine Fehlermeldung statt einer KI-Antwort	KI-Funktion, KI-Konfiguration und KI-Lizenz prüfen. Für persönliche Auskünfte zusätzlich die Kundenportal-Lizenz prüfen.
Meta meldet ein Token- oder Berechtigungsproblem	Gültigkeit und Rechte des Systembenutzer-Tokens sowie dessen Asset-Zuordnung prüfen.
Antwort nach langem Ausfall bleibt aus	Nach mehr als 24 Stunden wird die alte Nachricht nicht mehr beantwortet. Eine neue Frage öffnet ein neues Servicefenster.

Grenzen und Aufbewahrung

Die Verbindung gilt 90 Tage. STOP, TRENNEN oder Verbindung trennen in den Einstellungen heben sie auf. Ein neuer Link ersetzt die bisherige Verbindung und beginnt einen neuen Gesprächsverlauf.

Der Bot verarbeitet Textfragen. Bei aktivem Verkaufskanal kann er Beratungsanfragen als Leads erfassen. Mit Vorgänge bei Problemen erfassen können nicht verbundene Absender auch Probleme an die Schule melden. Andere Datenänderungen führt er hier nicht aus. Nach einem Versand-Timeout mit unbekanntem Ergebnis wird nicht automatisch nochmals gesendet. Die Person kann ihre Frage erneut stellen.

Der laufende Worker entfernt gespeicherte Bot-Nachrichten nach 30 Tagen. Der öffentliche Gesprächskontext umfasst höchstens zehn Nachrichten und läuft nach 30 Minuten ohne neue Frage ab. Ein Neustart des Workers oder STOP leert ihn. Für den persönlichen KI-Gesprächsverlauf gilt die separate Aufbewahrung des KI-Moduls. Nachrichten und Antworten werden über Meta und den konfigurierten KI-Anbieter verarbeitet.