get.chat einrichten: Anleitung für REST API und mehrere Webhooks

Inhaltsverzeichnis

Du richtest get.chat ein, indem du dich mit dem API-Schlüssel deines Kanals verbindest, eine erste Nachricht sendest und für jedes System, das deine WhatsApp-Ereignisse braucht, einen eigenen Webhook registrierst. get.chat ist die Technologie hinter 360Dialog Inbox. Die Inbox API ergänzt die offizielle WhatsApp Business API um eine REST API, die Weiterleitung an mehrere Webhooks und eine einbettbare Inbox-Oberfläche.[1] get.chat ist im Premium-Plan für 99 EUR pro Nummer und Monat enthalten.[2] Diese Anleitung führt dich vom API-Schlüssel bis zum geprüften Webhook für eingehende Nachrichten.

Das Wichtigste auf einen Blick

Du brauchst eine WhatsApp-Nummer im Premium-Plan von 360Dialog mit aktiviertem Inbox.
Die erste Nachricht an einen Kunden, der dir noch nie geschrieben hat, muss ein freigegebenes Template sein, also ein Nachrichtenformat, das Meta vorab genehmigt.
Für den Start reicht dein bestehender API-Schlüssel, und jedes System, das du später hinzufügst, bekommt einen eigenen Login für die API.
Beim Anlegen eines Webhooks legst du fest, welche Ereignisse er empfängt, angefangen bei den Nachrichten deiner Kunden.

Was du vor dem Start brauchst

Vor dem ersten API-Aufruf brauchst du fünf Dinge:

Ein Konto bei 360Dialog, in dem deine WhatsApp-Nummer verbunden und live ist.
Das aktivierte Inbox auf dieser Nummer. Es ist im Premium-Plan enthalten, und du aktivierst es für deinen Kanal im 360Dialog Hub.[3]
Die URL deines Inbox im Format https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/. Öffne das Inbox im 360Dialog Hub und kopiere die Adresse aus deinem Browser. Jede Nummer hat ein eigenes Inbox mit eigener URL.[4]
Den API-Schlüssel deines Kanals aus dem Hub. Das ist der geheime Schlüssel, der deine Nummer identifiziert, wenn du die WhatsApp API aufrufst. Wenn du einen neuen Schlüssel erzeugst, wird der alte ungültig. Verwende deshalb den bestehenden Schlüssel weiter, wenn eine andere Integration davon abhängt.[5]
Eine öffentlich erreichbare HTTPS-Adresse für jedes System, das Ereignisse erhalten soll.[6]

Alle Endpunkte in dieser Anleitung liegen unter /api/v1/ auf der Adresse deines Inbox.

Wenn du deine Nummer zum ersten Mal verbindest, kannst du mit API starten und den Premium-Plan wählen, damit das Inbox und seine API gleich dabei sind.

So authentifizierst du dich mit API-Schlüssel und Token pro Dienst

Die Inbox API akzeptiert für Einrichtung und Tests den API-Schlüssel deines Kanals und im Produktivbetrieb ein Token pro Dienst. Prüfe die Verbindung, indem du den Schlüssel im Header D360-Api-Key sendest:

curl -H "D360-Api-Key: YOUR_API_KEY" \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/current/

Die Antwort ist der Admin-Nutzer des Inbox, als der dich der API-Schlüssel anmeldet. Ein Schlüssel aus einem anderen Kanal liefert 403.

Für jeden Dienst einen Nutzer und ein Token anlegen

Jedes System, das mit dem Inbox arbeitet, braucht einen eigenen Nutzer, denn Webhooks, Zähler für neue Nachrichten, Berechtigungen und Audit-Logs gehören zu einem Nutzer. Lege ihn mit der Rolle app an, die nur API-Zugriff hat:

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/ \
  -H "D360-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "crm-sync", "profile": {"role": "app"}}'

Die Antwort enthält eine activation_url, die nur ein einziges Mal zurückkommt. Ruf sie auf, um das Token des Dienstes zu erhalten:

curl "ACTIVATION_URL"

{"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}

Speichere das Token bei den geheimen Zugangsdaten des Dienstes, denn die Aktivierungs-URL funktioniert nur einmal. Der Dienst sendet das Token mit dem Präfix Token:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

So sendest du deine erste Nachricht

Was du senden kannst, hängt vom Kundenservice-Fenster ab. Das ist der Zeitraum, in dem WhatsApp einem Unternehmen frei formulierte Nachrichten erlaubt. Das Fenster öffnet sich, wenn der Kunde dir schreibt, und gilt 24 Stunden ab seiner letzten Nachricht. Bei Gesprächen, die über eine Click-to-WhatsApp Ad oder die Schaltfläche „Nachricht senden“ einer Facebook- oder Instagram-Seite beginnen, sind es 72 Stunden.[7] Lies den Ablaufzeitpunkt im Chat aus contact.messaging_window_expires_at aus, denn die Dauer hängt davon ab, wie das Gespräch begonnen hat.[8]

Gesprächsstatus	Was du senden kannst
Der Kunde hat dir noch nie geschrieben	Nur ein Template
Der Kunde hat innerhalb des Fensters geschrieben	Text, Medien, interaktive Nachrichten oder ein Template
Das Fenster ist abgelaufen	Nur ein Template

Ein gesendetes Template öffnet ein neues Fenster.

Freitext in einem offenen Fenster senden

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/messages/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wa_id": "4915112345678", "type": "text", "text": {"body": "Hallo aus der Inbox API"}}'

Das Feld wa_id bezeichnet den Empfänger: eine Telefonnummer im internationalen Format ohne Pluszeichen oder eine Business-Scoped User ID (BSUID), wenn WhatsApp die Nummer der Person nicht weitergibt. Gib den Wert genau so zurück, wie du ihn aus dem Chat erhalten hast.

Für einen ersten Test öffnest du das Fenster selbst: Scanne im Inbox den QR-Code unter Open in WhatsApp mit deinem privaten Smartphone und sende eine Nachricht.

Ein Template senden, um ein neues Fenster zu öffnen

Hol deine freigegebenen Templates über GET /api/v1/templates/ ab und sende eines davon mit seinem Namen, im selben Format wie bei der WhatsApp API:

{
  "wa_id": "4915112345678",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": {"code": "en"}
  }
}

Die Antwortcodes lesen

Die Status „gesendet“, „zugestellt“ und „gelesen“ kommen später über deinen Webhook an, ebenso der Fehler 470 für einen Empfänger ohne WhatsApp.[9]

Code	Bedeutung	Was zu tun ist
202	Angenommen und zur Zustellung eingereiht	Auf Status-Ereignisse an deinem Webhook warten
400	Mit der Anfrage stimmt etwas nicht	Das Feld reason lesen
403	Nicht angemeldet oder keine Berechtigung für diesen Chat	Den Header und die Lese- und Schreibrechte des Nutzers prüfen
452	Der Empfänger ist kein gültiger WhatsApp-Nutzer	Die wa_id prüfen
453	Kundenservice-Fenster geschlossen	Ein freigegebenes Template senden

So konfigurierst du mehrere Webhooks auf einer Nummer

Ein Webhook ist die Adresse, an die WhatsApp die Ereignisse deiner Nummer liefert, und jede Nummer hat einen Haupt-Webhook. 360Dialog kann einer Nummer auch direkt weitere Webhook-URLs zuordnen. Mit jeder weiteren URL wird die Zustellung langsamer, deshalb empfehlen wir für Konten mit hohem Volumen einen einzigen Webhook.[10] Das Inbox empfängt den Haupt-Webhook und ruft den Webhook jedes Dienstes auf, den du verbindest. Jeder Aufruf ist ein HTTP-POST mit JSON-Body im Standardformat der WhatsApp-Webhooks.[11]

Webhooks gehören zu Nutzern. Der Nutzer, mit dessen Token ein Webhook angelegt wird, ist sein Eigentümer, und Nutzer ohne Admin-Rechte sehen nur ihre eigenen Webhooks.[12]

Einen Endpunkt anlegen

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/webhooks/waba/ \
  -H "Authorization: Token YOUR_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-backend.example.com/whatsapp", "on_incoming_message": true, "on_outgoing_message": true, "on_assigned": false, "headers": {"Authorization": "Bearer your-own-shared-secret"}}'

Die Ereignis-Flags setzen

Jedes Flag schaltet einen Ereignistyp ein oder aus. Setze deshalb beim Anlegen eines Webhooks jedes Flag ausdrücklich.

Feld	Liefert
on_incoming_message	Jede Nachricht, die ein Kunde an deine Nummer sendet
on_outgoing_message	Jede Nachricht, die aus dem Inbox gesendet wird, über den gehosteten Posteingang oder die API; für Systeme, die vollständige Kopien der Gespräche speichern
on_assigned	Einen Chat, der dem Nutzer dieses Webhooks zugewiesen wird, oder eine neue Nachricht in einem Chat, der ihm bereits zugewiesen ist; setze es, wenn ein Bot seine zugewiesenen Chats bearbeitet
on_message_echo	Nachrichten, die außerhalb des Inbox über die Messaging API von 360Dialog von deiner Nummer gesendet werden, als message_echoes-Payload von Meta
headers	Eigene Header, die bei jeder Zustellung mitgesendet werden

Deine Endpunkte verwalten

Aufruf	Funktion
GET /api/v1/webhooks/waba/	Listet Webhooks auf: Admins sehen die aller Nutzer, andere Nutzer nur ihre eigenen
POST /api/v1/webhooks/waba/	Legt einen Webhook an, Eigentümer ist der Nutzer des Tokens
GET /api/v1/webhooks/waba/{id}/	Zeigt einen Webhook an
PUT /api/v1/webhooks/waba/{id}/	Aktualisiert einen Webhook: Adresse, Ereignisse und Header
DELETE /api/v1/webhooks/waba/{id}/	Entfernt einen Webhook
GET /api/v1/webhooks/waba/{id}/test/	Sendet eine simulierte statuses-Zustellung an die Zieladresse

Dieselben Einstellungen findest du in deinen Inbox-Einstellungen unter WABA Webhooks (WABA steht für WhatsApp Business-Konto). Eine WhatsApp-Vertriebspipeline kann über einen eigenen Endpunkt laufen, unabhängig von anderen Systemen auf der Nummer.

Wenn du mehrere Systeme auf einer Nummer planst und eine zweite Meinung zur Aufteilung von Nutzern und Tokens möchtest, sprich mit uns, bevor du sie aufbaust.

So sicherst du Zustellungen ab und verarbeitest sie

Dein Endpunkt ist eine öffentliche Adresse, die Schreibzugriffe annimmt. Authentifiziere deshalb jede Zustellung mit einer von zwei Methoden:

Eigene Header. Das Feld headers wird bei jeder Zustellung mitgesendet, sodass dein Endpunkt ein eigenes Bearer-Token verlangen kann.
Ein gemeinsames Geheimnis in der Adresse, etwa https://your-backend.example.com/whatsapp?auth=SHARED_SECRET, für Systeme, die keine eigenen Header lesen können.

Jede Zustellung kommt im Standardformat der WhatsApp-Webhooks an. Gekürzt sieht eine eingehende Nachricht so aus:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "contacts": [{"profile": {"name": "Anna"}, "wa_id": "4915112345678", "user_id": "DE.13491208655302741918"}],
        "messages": [{"from": "4915112345678", "id": "wamid.ID", "type": "text", "text": {"body": "Hi"}}]
      }
    }]
  }]
}

Die Nachricht steht in messages[], der Absender in contacts[]. Die BSUID in user_id ist immer vorhanden, auch wenn WhatsApp die Telefonnummer verbirgt. Ordne Kunden deshalb zuerst über die BSUID zu.

Antworte schnell mit 200 und erledige langsame Arbeit danach. Nachrichten, die ein Webhook mit 200 bestätigt, gelten für den Nutzer dieses Webhooks als empfangen. So bleiben die Zähler für ungelesene Nachrichten in GET /api/v1/chats/ korrekt.

So bettest du das Inbox in deine Anwendung ein

Der Posteingang für Agenten ist eine Open-Source-React-App, die du mit einem einzigen iframe-Tag in ein bestehendes Tool einbettest.[13] Das eignet sich für Teams, die WhatsApp-Gespräche im Team verwalten und dafür ein internes Tool oder ein Kundenportal nutzen.

<iframe
  src="https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/?chat_only=1&hide_logo=1"
  allow="clipboard-write"
  width="420" height="700">
</iframe>

Ohne allow=“clipboard-write“ blockieren Browser das Kopieren innerhalb des Frames.

Parameter	Wirkung
chat_only=1	Blendet die Chatliste aus und zeigt ein einzelnes Gespräch
hide_logo=1	Entfernt das get.chat-Logo vom Ladebildschirm
lng=de	Legt die Sprache der Oberfläche per ISO-639-1-Code fest
bg_color=ff0000	Legt die Hintergrundfarbe als Hex-Wert ohne #-Zeichen fest
maximize=1	Entfernt die Außenabstände des Containers, damit das Inbox seinen Frame ausfüllt
cf_<filter>	Wendet beim Laden einen Chatfilter an, und zwar jeden Filter, den der Endpunkt chats unterstützt

Für ein eigenes Logo, einen eigenen Seitentitel, ein eigenes Favicon und ein eigenes App-Manifest musst du das Open-Source-Frontend selbst hosten. Variablen wie REACT_APP_TITLE, REACT_APP_LOGO_URL und REACT_APP_FAVICON_URL legst du dabei beim Build fest.[14]

Testcheckliste: deine Einrichtung von Anfang bis Ende prüfen

Führe diese Prüfungen der Reihe nach durch. Schlägt ein Schritt fehl, liegt das Problem genau in dieser Ebene.

Das Inbox läuft fehlerfrei. GET /api/v1/status/health/ liefert einen Status pro interner Prüfung.
Die Zugangsdaten sind gültig. GET /api/v1/users/current/ liefert für deinen API-Schlüssel den Admin-Nutzer und für ein Dienst-Token den eigenen Nutzer des Dienstes.
Das Fenster ist offen. Schreib deiner Business-Nummer von einem privaten WhatsApp-Konto aus, oder scanne im Inbox den QR-Code unter Open in WhatsApp.
Die Nachricht wird gesendet. POST /api/v1/messages/ mit einem Text liefert 202, und die Nachricht kommt auf dem Smartphone an.
Die Webhooks sind aufgelistet. GET /api/v1/webhooks/waba/ zeigt jeden Endpunkt und seinen Wert für on_incoming_message.
Der Endpunkt ist erreichbar. GET /api/v1/webhooks/waba/{id}/test/ sendet einen simulierten statuses-Payload ohne Nachricht. Dein Server protokolliert ihn und antwortet mit 200.
Die Weiterleitung funktioniert. Eine eingehende Nachricht vom Testgerät erreicht jeden registrierten Endpunkt. Nur dieser Schritt prüft deine Flags.
Das Inbox zeigt den Chat. Öffne das Inbox im 360Dialog Hub und prüfe das Gespräch.

Wenn das Testereignis nie ankommt, prüfe die HTTPS-Erreichbarkeit, eine schnelle 200-Antwort und eine eventuelle IP-Freigabeliste. Prüfe danach den Endpunkt unter WABA Webhooks in deinen Inbox-Einstellungen.

Wenn API-Schlüssel, Dienst-Tokens, Webhook-Flags und Checkliste bereitstehen, kannst du im Premium-Plan dein Inbox aktivieren und diese Einrichtung auf deiner eigenen Nummer umsetzen.

Häufig gestellte Fragen

Welche Authentifizierungsmethode verwendet die get.chat API?

Die Inbox API akzeptiert zwei Arten von Zugangsdaten. Der API-Schlüssel deines Kanals, gesendet im Header D360-Api-Key, meldet dich als Admin des Inbox an und eignet sich für Einrichtung und Tests. Im Produktivbetrieb nutzt jeder Dienst einen eigenen app-Nutzer mit eigenem Token, das bei jedem Aufruf als Authorization: Token YOUR_TOKEN mitgeht.

Kann ich mehrere Webhook-Endpunkte auf einer WhatsApp-Nummer registrieren?

Ja. Das Inbox empfängt den einen WhatsApp-Webhook und liefert jedes Ereignis erneut an jeden registrierten Endpunkt, jeweils mit eigenen Ereignis-Flags und Headern. Webhooks gehören jeweils einem Nutzer. Gib deshalb jedem System, das die Ereignisse verarbeitet, einen eigenen Nutzer und ein eigenes Token.

Warum empfängt mein Webhook keine eingehenden Nachrichten?

Ruf den Endpunkt mit GET /api/v1/webhooks/waba/{id}/ ab und prüfe, ob on_incoming_message auf true steht. Stell dann sicher, dass dein Endpunkt HTTPS-POST-Anfragen annimmt und schnell mit 200 antwortet. Sende anschließend mit GET /api/v1/webhooks/waba/{id}/test/ eine simulierte Zustellung, um die Verbindung zu testen.

Was passiert, wenn ich eine Nachricht außerhalb des Kundenservice-Fensters sende?

Die API liefert 453 mit dem Grund „Customer care messaging window expired.“ und stellt nichts zu. Sende ein freigegebenes Template, das ein neues Fenster öffnet.

Muss ich das Inbox selbst hosten, um es einzubetten?

Einbetten funktioniert mit deinem gehosteten Inbox: Richte ein iframe auf die Adresse des Inbox und passe es mit Query-Parametern an. Selbst hosten musst du das Open-Source-Frontend nur für Branding, das beim Build festgelegt wird, etwa für dein eigenes Logo, den Seitentitel und das Favicon.

Kann eine get.chat-Instanz mehrere WhatsApp-Nummern bedienen?

Jede Nummer hat ein eigenes Inbox mit eigener Adresse, eigenen Servern, eigener Datenbank und eigenen Nutzern. Mehrere Nummern bedeuten mehrere Inbox-Instanzen, und dein Dienst verbindet sich mit jedem einzeln.

Quellen

[1] 360Dialog Documentation, „Inbox API.“ https://docs.360dialog.com/docs/inbox/inbox-api Accessed September 30, 2026.

[2] 360Dialog, „WhatsApp Business Platform Pricing.“ https://360dialog.com/pricing Accessed September 25, 2026.

[3] 360Dialog Documentation, „Quickstart“ (Hosted Inbox). https://docs.360dialog.com/docs/inbox/hosted-inbox/quickstart Accessed September 30, 2026.

[4] 360Dialog Documentation, „Quickstart“ (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/quickstart Accessed September 30, 2026.

[5] 360Dialog Documentation, „Authentication“ (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/authentication Accessed September 30, 2026.

[6] 360Dialog Documentation, „Making Requests“ (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/reference/making-requests Accessed September 30, 2026.

[7] 360Dialog Documentation, „The Customer Service Window.“ https://docs.360dialog.com/docs/inbox/the-customer-service-window Accessed September 30, 2026.

[8] 360Dialog Documentation, „Sending Messages“ (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/sending-messages Accessed September 30, 2026.

[9] 360Dialog Documentation, „Messages“ (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/messages Accessed September 30, 2026.

[10] 360Dialog Partner Documentation, „Set multiple webhooks for Phone Number.“ https://docs.360dialog.com/partner/onboarding/webhook-events-and-setup/set-multiple-webhooks-for-phone-number Accessed September 28, 2026.

[11] 360Dialog Documentation, „Receiving Messages“ (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/receiving-messages Accessed September 30, 2026.

[12] 360Dialog Documentation, „Webhooks“ (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/webhooks Accessed September 30, 2026.

[13] get.chat documentation, „Embed and White-Label the Inbox.“ https://docs.getchat.360dialog.io/guides/2-embedding-the-inbox/ Accessed September 25, 2026.

[14] get.chat, „get.chat Web App“ README. https://github.com/get-chat/web-app Accessed September 25, 2026.