Zum Hauptinhalt springen
connic
Starte kostenlos

WhatsApp

Lass einen Agenten WhatsApp-Nachrichten an deine Geschäftsnummer beantworten, auch mit Fotos und Dokumenten. Antworten gehen von derselben Nummer raus, und freigegebene Vorlagen erreichen alle, die in den letzten 24 Stunden nicht geschrieben haben.

Modi
Inbound, Outbound
Einrichtung
Dashboard oder connectors/*.yaml
Dokumentation
WhatsApp Docs
Publisher
Von connic

Setz einen Agenten auf deine Geschäftsnummer

Speichere eine Connection mit deiner Meta-App und wähle eine Telefonnummer. Sobald du eine eingehende Verbindung speicherst, leitet connic die Nachrichten dieser Nummer an den Agenten.

Eine Connection pro Meta-App
Die Connection enthält App ID, App Secret, Systemnutzer-Token und die ID des WhatsApp Business Accounts. Jede Verbindung darauf wählt eine Telefonnummer dieses Kontos.
Webhook beim Speichern eingerichtet
connic abonniert für die App das Konto und setzt die Callback-URL der Nummer. Andere Nummern behalten ihre Einstellungen, und beim Löschen der Verbindung entfernt connic die Callback-URL wieder.
Eine eingehende Verbindung pro Nummer
Eine Nummer schickt ihre Nachrichten an genau eine eingehende Verbindung. Ausgehende Verbindungen können von derselben Nummer senden.
Was beim Agenten ankommt
NachrichtWas connic tut
TextStartet einen Run mit text
Bild, Audio, Video, Dokument, StickerStartet einen Run mit files und der Bildunterschrift
Antworten auf Buttons und ListenStartet einen Run mit dem Titel als text
Standort, KontakteStartet einen Run mit raw
ReaktionenWerden ignoriert
Zustell- und LesebestätigungenLogs der Verbindung

Jede Nachricht geprüft und lesbar

WhatsApp signiert jede Zustellung mit deinem App Secret. connic prüft die Signatur und startet dann alle verknüpften Agenten mit Text, Absender und Datei.

Geprüfte Zustellungen
connic prüft X-Hub-Signature-256 mit dem App Secret. Stellt WhatsApp eine Nachricht erneut zu, landet sie im selben Run.
Dateien aus der Nachricht
Bilder, Audio, Video, Dokumente und Sticker kommen in files an, die Bildunterschrift als text. Dateien über 32 MB stehen in file_issues.
Absender mit oder ohne Nummer
from enthält die Telefonnummer, wenn die Person sie teilt. user_id kennzeichnet jeden Absender, und Antworten erreichen beide.
Gesprächsverlauf
conversation_id steht für eine Person an einer Nummer. Setze session.key auf input.conversation_id, dann teilen sich Folgenachrichten eine Session.
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
  "type": "text",
  "text": "Has order ord_8812 shipped yet?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "name": "Jana",
  "conversation_id": "whatsapp:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091",
  "raw": { ... }
}
agents/whatsapp-support.yaml
session:
  key: input.conversation_id
  ttl: 86400

Innerhalb von 24 Stunden antworten oder eine Vorlage senden

Verknüpfe eine ausgehende Verbindung mit derselben Connection und Nummer. Sie sendet nach dem Run, wenn der Agent sie als Tool aufruft oder wenn Middleware sie aufruft.

Reihenfolge der Empfänger
Zuerst zählt ein ausdrückliches to, dann der Standardempfänger der Verbindung, dann die Person, die geschrieben hat.
Antworten mit Text
Bis zu 4.096 Zeichen, innerhalb von 24 Stunden nach der letzten Nachricht der Person.
Freigegebene Vorlagen
Außerhalb dieses Fensters sendest du template mit Name, Sprache und Parametern einer Vorlage, die Meta für dein Konto freigegeben hat.
Zustellbestätigungen
Die Ausgabe des Runs enthält die Nachrichten-ID von WhatsApp. Bestätigungen für gesendet, zugestellt, gelesen und fehlgeschlagen stehen in den Logs der eingehenden Verbindung auf derselben Nummer.
reply.json
{
  "text": "Yes, ord_8812 left our warehouse today and arrives on Friday."
}
template.json
{
  "to": "+4917612345678",
  "template": {
    "name": "appointment_reminder",
    "language": "en_US",
    "parameters": ["Jana", "10:30"]
  }
}

Beide Richtungen im Code festlegen

Lege die eingehende und die ausgehende Verbindung als YAML-Dateien in connectors/ an. Beide verweisen per Name auf die WhatsApp-Connection, die Dateien enthalten also keine Zugangsdaten, und jedes Deployment legt sie für seine Umgebung an oder aktualisiert sie.

connectors/support-whatsapp.yaml
type: whatsapp
mode: inbound
connection: support-whatsapp
config:
  phone_number_id: "106540352242922"
agents:
  - whatsapp-support
connectors/support-whatsapp-replies.yaml
type: whatsapp
mode: outbound
connection: support-whatsapp
config:
  phone_number_id: "106540352242922"
agents:
  - name: whatsapp-support
    outbound: { usage: automatic, source: [support-whatsapp] }

Wo WhatsApp passt

Wähle ein Szenario und sieh, was von WhatsApp ankommt und was der Agent zurückschickt.

Ein Kunde schickt ein Foto einer Fehlermeldung, und der Agent antwortet mit der Lösung.

Kunde auf WhatsApp
WhatsApp eingehend
product-support
Antwort auf WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDVBMjA0N0Q5RTQ2MEI3MUQ4NjAA",
  "type": "image",
  "text": "The coffee machine shows this error. What should I do?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:4c2a9e1b-7f3d-5b8e-a6c4-0d2f8e1a3b5c",
  "files": [
    {
      "name": "image-1184303612398871.jpg",
      "mime_type": "image/jpeg",
      "data": "<base64-bytes>",
      "size": 182344
    }
  ]
}
outbound-run-output.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABEYEjdCMjA5RjE0QzM2RDU4NEU2AA==",
  "wa_id": "4917612345678"
}

Ein Kunde fragt nach einer Bestellung, und der Agent schlägt sie nach und antwortet von deiner Nummer.

Kunde auf WhatsApp
WhatsApp eingehend
order-status
Antwort auf WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
  "type": "text",
  "text": "Has order ord_8812 shipped yet?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091"
}
outbound-run-output.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABEYEjFBM0Q1QzdFOUIyRjRBNkM4AA==",
  "wa_id": "4917612345678"
}

Ein täglicher Zeitplan startet den Agenten, und er schickt allen mit einem Termin am nächsten Tag eine freigegebene Vorlage.

Täglicher Zeitplan
Cron
appointment-reminders
Vorlage auf WhatsApp
input.json
{
  "trigger": "cron",
  "schedule": "0 7 * * *",
  "triggered_at": "2026-10-14T07:00:00",
  "prompt": "Remind every customer who has an appointment tomorrow."
}
agent-tool-payload.json
{
  "to": "+4917612345678",
  "template": {
    "name": "appointment_reminder",
    "language": "en_US",
    "parameters": ["Jana", "10:30"]
  }
}

Ein Kunde tippt in der Erinnerung auf Verschieben, und der Agent schlägt freie Termine vor.

Antwort per Button
WhatsApp eingehend
appointment-desk
Freie Termine auf WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDhDMkU0QTZCOEQwRjJBNEM2RThBAA==",
  "type": "button",
  "text": "Reschedule",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:4c2a9e1b-7f3d-5b8e-a6c4-0d2f8e1a3b5c"
}
agent-output.json
{
  "text": "No problem. Thursday 14:00 and Friday 9:30 are free. Which one suits you?"
}

FAQ zu WhatsApp

Eine Meta-App mit WhatsApp, ein WhatsApp Business Account mit einer Telefonnummer und das Token eines Systemnutzers für die App mit den Berechtigungen business_management, whatsapp_business_management und whatsapp_business_messaging. App ID, App Secret, Token und Account-ID trägst du einmal in einer Connection ein.

Nichts. connic setzt die Callback-URL nur für die Nummer der Verbindung, die anderen Nummern senden weiter an die Callback-URL deiner App. Hat die Nummer schon eine eigene Callback-URL, schlägt das Speichern fehl, statt sie zu ersetzen.

Ja, mit einer freigegebenen Vorlage. Verknüpfe eine ausgehende Verbindung mit einem Agenten, den ein Zeitplan, ein Webhook oder eine andere Verbindung startet, und übergib to und template mit der Nachricht. Antworten mit Text erreichen eine Person nur innerhalb von 24 Stunden nach ihrer letzten Nachricht.

Nur mit einer Session. Setze session.key am Agenten auf input.conversation_id und stelle ihn erneut bereit. Nachrichten derselben Person an dieselbe Nummer teilen sich dann eine Session, solange sie besteht.

Er heißt, dass WhatsApp die Nachricht angenommen hat. Ob sie auf dem Telefon angekommen ist, meldet WhatsApp später, und eine eingehende Verbindung auf derselben Nummer schreibt diese Bestätigungen in ihre Logs.