Agenten mit WhatsApp-Nachrichten an deine Geschäftsnummer starten und ihre Antworten oder freigegebene Vorlagen senden.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | whatsapp |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ whatsapp mit einer Meta-App und dem Token eines Systemnutzers |
| Bridge | Nicht unterstützt |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jede Nachricht startet alle verknüpften Agenten. |
| Telefonnummer | Eine Inbound-Verbindung pro Nummer. Outbound-Verbindungen können sie mitnutzen. |
| Während der Pause | Nachrichten erhalten 200 und starten keine Runs. Outbound sendet nichts. |
Einrichtung
Öffne in den Meta Business Settings Users → System users und lege einen Systemnutzer an. Gib ihm unter Assign assets volle Kontrolle über deine Meta-App und Zugriff auf das WhatsApp Business Account. Klicke auf Generate token, wähle die App und erteile
business_management,whatsapp_business_managementundwhatsapp_business_messaging.Kopiere im Meta App Dashboard unter App settings → Basic die App ID und das App secret. Kopiere auf der Seite WhatsApp → API Setup der App die WhatsApp Business Account ID und die Phone number ID der Nummer, die deine Agenten nutzen.
Klicke in connic unter Projekt-Settings → Connections auf New connection und wähle WhatsApp. Den Kontozugang kannst du auch im Formular der Verbindung über die Auswahl unter Connection anlegen. Gib einen Name, die App ID, das App secret, das Access token und die WhatsApp Business Account ID ein und klicke auf Create connection.
Öffne den Agenten. Klicke im Connector Flow für eingehende Nachrichten auf Add inbound connector oder für Antworten auf Add outbound connector. Klicke dann auf Create New Connector und wähle WhatsApp.
Wähle den Modus, Inbound (Incoming messages) oder Outbound (Send messages), unter Connection den Kontozugang und trag die Phone number ID ein. Klicke auf Create. Eine Inbound-Verbindung richtet dabei den Webhook der Nummer ein; siehe Webhook der Telefonnummer. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.
Konfiguration
Die Felder einer WhatsApp-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | whatsapp. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Required | Inbound und Outbound. Name oder ID eines WhatsApp-Kontozugangs. Dashboard: Connection. |
| config | object | Required | Einstellungen der WhatsApp-Verbindung. |
| phone_number_id | string | Required | Inbound und Outbound. Die ID einer Telefonnummer im WhatsApp Business Account des Kontozugangs. Inbound-Verbindungen erhalten ihre Nachrichten, Outbound-Verbindungen senden von ihr. Dashboard: Phone number ID. |
| to | string | Optional | Outbound. Eine Telefonnummer im Format E.164, etwa +4915112345678, an die jede Nachricht geht. Ohne sie gehen Antworten an die Person, deren Nachricht den Run gestartet hat. Dashboard: Default recipient. |
App ID, App Secret, Access Token und WhatsApp Business Account ID gehören zum Kontozugang, nicht zur Verbindung.
Erzeugte Werte
connic setzt diese Werte, wenn du die Verbindung oder ihren Kontozugang speicherst.
| Wert | Modi | Beschreibung |
|---|---|---|
| Webhook-URL | Inbound | Die URL, die connic beim Speichern der Verbindung als Callback-URL der Telefonnummer einträgt. |
| Telefonnummer | Inbound, Outbound | Die Rufnummer, wie WhatsApp sie anzeigt. Du siehst sie in den Details der Verbindung. |
| Verify Token | Inbound, Outbound | Ein zufälliges Token, das connic im Kontozugang speichert. WhatsApp schickt es zurück, wenn es die Webhook-URL prüft. |
Agent-Input
Modi: Inbound
Eine Inbound-Verbindung startet einen Run für jeden verknüpften Agenten, sobald jemand ihrer Telefonnummer eine Nachricht schickt. Der Run erhält:
{
"message_id": "wamid.HBgNNDkxNTExMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
"type": "text",
"text": "Hallo, wo ist meine Bestellung 4711?",
"from": "+4915112345678",
"user_id": "US.13491208655302741918",
"name": "Jana Schmidt",
"to": "4930123456789",
"conversation_id": "whatsapp:5f0c2a9e-1b7d-5c3a-9e2f-7a4b6d8c0e13",
"raw": { ... }
}message_idist die ID der Nachricht bei WhatsApp,typeihre Art, etwatext,image,document,interactiveoderlocation.textist der Text der Nachricht, die Bildunterschrift einer Datei oder der Titel des Buttons oder Listeneintrags, den die Person angetippt hat. Bei anderen Arten bleibt er leer.fromist die Telefonnummer des Absenders. Teilt jemand seine Nummer nicht mit dem Unternehmen, lässt WhatsApp sie weg; dann steht dortnull.user_idist die WhatsApp-Nutzer-ID des Absenders für dein Unternehmen, die jede Nachricht mitbringt.nameist der Profilname des Absenders bei WhatsApp,todie Geschäftsnummer, die die Nachricht erhalten hat.conversation_idbleibt für alle Nachrichten einer Person an die Nummer gleich. Soll dein Agent die früheren Nachrichten als Verlauf kennen, setze in seiner YAMLsession.key: input.conversation_id. Von sich aus schaltet der Connector keine Sessions ein.- Bilder, Audio, Video, Dokumente und Sticker kommen in
files. Eine Datei, die connic nicht übernehmen konnte, steht infile_issues. rawist die Nachricht, wie WhatsApp sie geschickt hat.
Reaktionen und Nachrichten, die WhatsApp als nicht unterstützt markiert, starten keine Runs. Stellt WhatsApp eine Nachricht erneut zu, startet sie keinen weiteren Run. Die Statusmeldungen zu ausgehenden Nachrichten (gesendet, zugestellt, gelesen, fehlgeschlagen) erscheinen in den Logs der Verbindung. Von sich aus antwortet der Inbound-Modus nicht: Verknüpfe den Agenten dafür mit einer Outbound-Verbindung für WhatsApp, die denselben Kontozugang und dieselbe Telefonnummer nutzt; siehe Outbound-Zustellung.
Webhook der Telefonnummer
Modi: Inbound
Beim Speichern einer Inbound-Verbindung abonniert connic für die App des Kontozugangs das WhatsApp Business Account, falls das noch nicht geschehen ist, und trägt die Webhook-URL der Verbindung als Callback-URL ihrer Telefonnummer ein. Nur die Nachrichten dieser Nummer kommen bei connic an; die übrigen Nummern des Kontos senden weiter an die Callback-URL der App. Löschst du die Verbindung, entfernt connic die Callback-URL der Nummer wieder.
connic prüft die Signatur jeder Zustellung mit dem App Secret. Hat die Nummer schon eine eigene Callback-URL, schlägt das Speichern fehl, damit connic nie den Webhook eines anderen Systems ersetzt. Entferne diese Callback-URL zuerst bei Meta.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-Verbindung für WhatsApp sendet bei jeder Nutzung eine Nachricht von ihrer Telefonnummer: wenn der Run eines verknüpften Agenten endet, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Den Empfänger bestimmt die erste Regel, die zutrifft:
toim Output oder Payload: eine Telefonnummer im Format E.164 oder eine WhatsApp-Nutzer-ID.- Der Default recipient der Verbindung.
- Die Person, deren Nachricht den Run gestartet hat, wenn eine Inbound-Verbindung für WhatsApp mit demselben Kontozugang und derselben Telefonnummer sie empfangen hat.
Automatischer Output
Eine automatische Verknüpfung sendet den finalen Output des Runs. Reiner Text wird zur Nachricht. Bei einem JSON-Objekt kommt der Text aus text, body, message, response oder output, in dieser Reihenfolge; to legt den Empfänger fest.
{
"text": "Deine Bestellung 4711 hat heute unser Lager verlassen und kommt am Freitag an."
}Vorlagen
Mehr als 24 Stunden nach der letzten Nachricht einer Person, und an alle, die noch nicht geschrieben haben, stellt WhatsApp nur Vorlagen zu, die Meta für dein Konto freigegeben hat. Setze dann statt Text template mit dem name der Vorlage, ihrem Sprachcode in language und den parameters: eine Liste von Strings für nummerierte Parameter oder ein Objekt für benannte.
{
"to": "+4915112345678",
"template": {
"name": "order_update",
"language": "de",
"parameters": ["Jana", "4711"]
}
}Payload für Agent-Tool und Middleware
Das Modell oder die Middleware übergibt text oder template und optional to, im selben Format wie der Output oben. Andere Felder werden abgelehnt.
Zustellung und Wiederholungen
Bremst WhatsApp eine Nachricht per Rate Limit, wartet connic und sendet sie erneut. Die Runs der Verbindung zeigen jede Nachricht mit ihrer ID bei WhatsApp oder mit dem Fehler. Ob eine Nachricht das Telefon erreicht hat, meldet WhatsApp später in den Statusmeldungen, die eine Inbound-Verbindung auf derselben Nummer protokolliert.
Limits und Fehler
| Limit | Wert |
|---|---|
| Kundenservice-Fenster | Antworten mit Text erreichen eine Person nur innerhalb von 24 Stunden nach ihrer letzten Nachricht. Danach stellt WhatsApp nur noch freigegebene Vorlagen zu. |
| Textlänge | 4.096 Zeichen pro Nachricht. |
| Eingehende Dateien | Eine Datei pro Nachricht, bis zu 32 MB im Input des Runs. WhatsApp selbst nimmt Bilder bis 5 MB, Audio und Video bis 16 MB und Dokumente bis 100 MB an; größere Dateien stehen in file_issues. |
| Fehlgeschlagene Zustellungen | WhatsApp stellt einen Webhook, der nicht mit 200 beantwortet wird, bis zu 7 Tage lang erneut zu. |
| Sendetempo | WhatsApp begrenzt die Nachrichten pro Nummer, pro Konto und pro Empfänger. Bremst WhatsApp per Rate Limit, wartet connic und sendet erneut. |
Anfragen ohne gültige Signatur erhalten 401. Das Speichern einer Verbindung schlägt fehl, wenn Access Token oder App Secret falsch sind, wenn die Telefonnummer nicht im WhatsApp Business Account liegt und bei Inbound-Verbindungen, wenn die Nummer schon eine eigene Callback-URL hat oder zu einer anderen connic-Verbindung gehört. Eine Nachricht schlägt fehl, wenn WhatsApp sie ablehnt, etwa Text außerhalb des 24-Stunden-Fensters oder eine Vorlage ohne Freigabe.