Um die WhatsApp API vor der Registrierung einer Nummer zu testen, forderst du per WhatsApp einen Sandbox-API-Key an, verbindest einen HTTPS-Webhook und sendest Nachrichten und Templates an dein eigenes Telefon. Die Sandbox ist kostenlos und sofort verfügbar.[9] Entwickler können noch am selben Tag mit der Integration beginnen, ohne Business-Nummer, Kontofreigabe oder Vertriebsgespräch. Jeder Test läuft auf dem eigenen Telefon des Entwicklers und erreicht keine echten Kunden. Ist das Unternehmen bereit für den Livebetrieb, zieht der getestete Code mit neuer Serveradresse, neuem API-Key und neuem Webhook um.
Das Wichtigste auf einen Blick
- Ein Sandbox-API-Key kommt als WhatsApp-Antwort auf eine einzige START-Nachricht, ohne registrierte Nummer und ohne Vertriebsgespräch.
- Jeder Sandbox-Key deckt bis zu 200 Nachrichten ab, abgelehnte Anfragen eingeschlossen, alle an einen festen Empfänger: das eigene WhatsApp des Testers.
- Die Sandbox prüft die Authentifizierung des Codes, eingehende Webhook-Events und die Struktur von Nachrichten- und Template-Anfragen.
- Tests, die die Regeln einer regulären Business-Nummer brauchen, gehören auf eine von Meta bereitgestellte 555-Nummer, die wie jede reguläre Nummer zu Standardpreisen abgerechnet wird.
- 360Dialog, ein Official Meta Solution Partner, stellt die Sandbox und den produktiven Zugang zur WhatsApp Business API bereit.
Was ist die WhatsApp API Sandbox?
Die WhatsApp API Sandbox ist eine Testumgebung von 360Dialog, die Freitextnachrichten und Templates an einen festen Empfänger sendet: das eigene WhatsApp-Konto des Testers.[1] Entwickler prüfen damit den Codepfad: den Auth-Header, den Webhook und die Struktur der Payload. Jedes Testkonto erhält einen eigenen API-Key, der an diesen einen Empfänger gebunden ist.
Dieser Empfänger ist die Telefonnummer des Testers, auch ein Festnetzanschluss, auf dem WhatsApp läuft. Teilt der Tester seine Nummer nicht, ist der Empfänger eine „Business-Scoped User ID“ (BSUID). Auf dem Testtelefon übernimmt der Tester die Rolle des Kunden: Er sendet Nachrichten an die Sandbox und erhält die Antworten.
Wie bekommst du einen Sandbox-API-Key?
Sende das Wort START per WhatsApp an die Sandbox-Nummer von 360Dialog, und der Sandbox-API-Key kommt als Antwort zurück. Eine einzige Nachricht vom Testtelefon ist die ganze Anfrage. Jeder Sandbox-API-Aufruf trägt diesen Key danach im Header.
Die Sandbox-Nummer steht auf der Sandbox-Seite unserer Dokumentation, zusammen mit einem Click-to-Chat-Link und einem QR-Code. START muss in Großbuchstaben stehen. WhatsApp fragt den Tester eventuell, ob er seine Kontaktdaten teilen möchte. Lehnt er ab oder antwortet er spät, kommt der Key trotzdem innerhalb von 5 Minuten an, zusammen mit einer BSUID.
Diesem Konto ist keine Telefonnummer zugeordnet. Jede Anfrage von diesem Konto trägt die BSUID im Feld recipient und lässt to weg. Wer vorab prüft, welche Kennung der Key verwendet, erspart sich eine Runde HTTP-403-Fehler.
Wie richtest du den Sandbox-Webhook ein?
Der Sandbox-Webhook ist die HTTPS-Adresse, an der der Code die eingehenden Nachrichten des Testers empfängt, dazu ein Status-Update für jede Nachricht, die die API sendet. Ein einziger API-Aufruf registriert ihn. Ist der Webhook zuerst eingerichtet, erscheint jeder spätere Test als Event, das der Code auswerten kann.
Registriere die Adresse auf dem Sandbox-Host, mit dem Key im Header:
curl -X POST https://waba-sandbox.360dialog.io/v1/configs/webhook \
-H 'Content-Type: application/json' \
-H 'D360-API-KEY: <YOUR_API_KEY>' \
-d '{"url": "<YOUR_HTTPS_WEBHOOK_URL>"}'Ein erfolgreicher Aufruf liefert HTTP 200 mit der URL zurück. Eine einfache http-Adresse scheitert mit HTTP 400 und der Meldung „url must be HTTPS“. Für schnelle Tests vergeben webhook.site und RequestBin temporäre HTTPS-Adressen, und ngrok tunnelt einen lokalen Port. Mit demselben Aufruf tauschst du die Webhook-Adresse jederzeit aus.
Schreib der Sandbox-Nummer zur Kontrolle noch einmal vom Testtelefon aus. Ein eingehendes Event kommt unter entry[].changes[].value an, und auf jede ausgehende Nachricht folgen die Status gesendet, zugestellt und gelesen. Konten mit Telefonnummer erhalten wa_id, from und recipient_id. BSUID-Konten erhalten stattdessen user_id, from_user_id und recipient_user_id.
Wie sendest du deine erste Nachricht und dein erstes Template?
Sende einen kurzen Text über die API an das eigene WhatsApp des Testers und danach ein Template über denselben Aufruf. Kommen Text und Template an, funktionieren Authentifizierung, Anfrageformat und Status-Events durchgängig.
Der Text geht an /v1/messages auf dem Sandbox-Host, mit denselben beiden Headern:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<YOUR_PHONE_NUMBER>",
"type": "text",
"text": { "body": "Hello from the sandbox" }
}Jede Anfrage braucht das Feld messaging_product. Der Wert von to muss genau der Nummer entsprechen, an die der Key gebunden ist, und BSUID-Konten senden stattdessen "recipient": "<YOUR_BUSINESS_SCOPED_USER_ID>". Ein anderer Wert oder eine Anfrage ohne beide Felder ergibt HTTP 403. Eine gültige Anfrage liefert HTTP 201 mit einer Nachrichten-ID.
Die Sandbox bietet drei feste Templates:
| Template | Was du damit testest |
|---|---|
disclaimer | Eine feste Textnachricht ohne Parameter und mit leerem components-Array |
first_welcome_messsage | Einen Parameter im Textkörper, der den Namen des Empfängers einsetzt |
interactive_template_sandbox | Ein Template mit zwei Buttons |
Eine Template-Anfrage setzt "type": "template", den Namen des Templates und den Sprachcode en.
Was kannst du in der Sandbox nicht tun?
Die Sandbox kann niemanden außer ihrem festen Empfänger erreichen, keine Templates außerhalb ihrer drei vorgegebenen senden, keine Medien per Medien-ID hochladen oder abrufen und nicht mehr als 200 Nachrichten senden. Wer diese Grenzen vorab kennt, sieht, welche Tests auf eine registrierte Nummer gehören.
Jede Anfrage, die bis zur Messaging-API durchkommt, verbraucht eine der 200 Nachrichten, auch wenn die Nachricht abgelehnt wird. Sind alle 200 verbraucht, gibt die Sandbox HTTP 429 zurück. Wer Payloads vor jedem Versand prüft, spart das Kontingent für echte Tests.
Eine Live-Nummer geht mit jeder dieser Grenzen anders um:
| Grenze der Sandbox | Auf einer Live-Nummer |
|---|---|
| Ein fester Empfänger | Kunden: Freitextnachrichten innerhalb eines offenen Kundenservice-Fensters, außerhalb davon Templates[2] |
| Drei vorgegebene Templates | Die eigenen Templates des Unternehmens, jedes vor der Nutzung freigegeben (warum Templates abgelehnt werden) |
| Keine Medien per Medien-ID | Hochladen, Abrufen und Löschen per Medien-ID, Dateien bleiben 30 Tage nach der letzten Nutzung gespeichert[3] |
| 200 Nachrichten | Die Messaging-Limits von Meta für die Nummer |
Sandbox oder von Meta bereitgestellte 555-Nummer: Was solltest du nutzen?
Die Sandbox eignet sich für eine erste Prüfung des Codes gegen die API, eine von Meta bereitgestellte 555-Nummer für Tests, die eine reguläre Business-Nummer auf der WhatsApp Business Platform brauchen. Die Wahl entscheidet, was der Test beweist und was später neu gebaut werden muss.
| Frage | Sandbox | Von Meta bereitgestellte 555-Nummer |
|---|---|---|
| Was sie beweist | Authentifizierung, Webhook-Verarbeitung und Payload-Struktur | Verhalten unter den Regeln einer regulären Business-Nummer |
| Wer sie ausgibt | 360Dialog | Meta, das sie auch verwaltet |
| Ideal für | Code-Prüfungen | Onboarding, Evaluierung, Integrationstests, Demos und interne QA |
| Wohin sie wechseln kann | Bleibt an einen Testempfänger gebunden | Kann weder zu einem anderen WhatsApp Account wechseln noch die WhatsApp Business Platform verlassen |
Berechtigte Unternehmen können während des Embedded Signup bis zu zwei 555-Nummern von Meta erhalten, jeweils mit der US-Ländervorwahl +1 und der Ortsvorwahl 555.[4] Eine 555-Nummer wird automatisch verifiziert und folgt den regulären Preisregeln und Qualitätsbewertungen. Der Anzeigename braucht trotzdem vor der ersten Nachricht eine Freigabe. Wir rechnen jede 555-Nummer wie eine reguläre Nummer zu Standardpreisen ab und erstatten keine 555-Nummern, die versehentlich eingerichtet wurden.[5] Echter Kundenverkehr gehört auf eine reguläre Nummer, weil sich Einrichtung und Verlauf einer 555-Nummer nicht auf eine neue Nummer übertragen lassen.
Was ändert sich beim Wechsel von der Sandbox zu einer Live-Nummer?
Beim Wechsel zu einer Live-Nummer ändern sich Serveradresse, API-Key und Webhook. Der Authentifizierungs-Header bleibt gleich. Wer diese Änderungen vor dem Umstieg plant, kann den Sandbox-Code weiterverwenden.
Eine Live-Nummer braucht ein freigegebenes WhatsApp Business-Konto (WABA), eine registrierte Telefonnummer, einen API-Key und einen HTTPS-Webhook. Meta teilt das WABA in einen WhatsApp Account, der die Telefonnummer hält, und einen Messaging Account, der Templates, Abrechnung und Webhook-Abonnements hält.[6] Nummern, die über Embedded Signup eingerichtet werden, registriert Meta ausschließlich für die WhatsApp Cloud API. Drei Dinge ändern sich in Code und Konfiguration:
- Host und Pfad: Nachrichten gehen an
https://waba-v2.360dialog.io/messages, ohne das Präfix/v1des Sandbox-Pfads. Der HeaderD360-API-KEYbleibt. - API-Key: Jede Telefonnummer erhält im 360Dialog Hub einen eigenen Key.[7] Speichere den Key, sobald er erscheint, denn der Hub zeigt ihn nur einmal an. Ein neuer Key widerruft alle früheren. Für Partnerkunden erstellt der Integrationspartner den Key.
- Webhook: Ersetze die temporäre Adresse von webhook.site, RequestBin oder ngrok durch einen stabilen HTTPS-Endpunkt mit gültigem SSL-Zertifikat. Seine Domain darf keine Unterstriche und keine expliziten Ports enthalten.[8] Lege den Endpunkt auf die Status-Callbacks aus, die zusätzlich zum eingehenden Traffic etwa das Dreifache des ausgehenden Volumens ausmachen. Meta wiederholt fehlgeschlagene Zustellungen bis zu 7 Tage lang.
Ein Sandbox-Durchlauf klärt Authentifizierung, Webhooks und Payloads, bevor eine Nummer, eine Template-Freigabe oder ein Kunde ins Spiel kommt. Das Team verbringt die ersten Tage auf einer Live-Nummer dann mit den eigentlichen Gesprächen.
Der produktive Zugang zur WhatsApp Business API von 360Dialog, einem Official Meta Solution Partner, nutzt denselben Header D360-API-KEY wie die Sandbox. Registriere eine Nummer und stelle den getesteten Code auf den Produktions-Host um: Mit API starten.
Häufig gestellte Fragen
Warum sendet die WhatsApp Sandbox meine Nachricht nicht?
Eine Sandbox-Nachricht scheitert, wenn Key, Empfänger oder Nachrichtenkontingent nicht zu dem passen, was die Sandbox erwartet. HTTP 401 bedeutet, dass der Header D360-API-KEY fehlt oder ungültig ist. Eine 403-Antwort bedeutet, dass der Wert von to oder recipient von dem abweicht, an den der Key gebunden ist, oder dass die Anfrage keines der beiden Felder enthält. Ist das Limit von 200 Nachrichten aufgebraucht, gibt die Sandbox HTTP 429 zurück.
HTTP 502 und HTTP 504 bedeuten, dass die Nachricht die Messaging-API nicht rechtzeitig erreicht hat. Sende die Anfrage später erneut.
Kann die WhatsApp Sandbox Nachrichten an mehr als eine Nummer senden?
Nein, die WhatsApp Sandbox sendet nur an den einen Empfänger, an den ihr API-Key gebunden ist: die Telefonnummer oder die Business-Scoped User ID des Testers. Jeder andere Wert in der Anfrage ergibt HTTP 403. Tests mit dem Telefon eines Kollegen, einem QA-Gerät oder einer Gruppe von Nutzern brauchen eine Nummer auf der WhatsApp Business Platform, etwa eine registrierte Business-Nummer oder eine von Meta bereitgestellte 555-Nummer.
Kannst du eigene Templates in der WhatsApp Sandbox nutzen?
Nein, die WhatsApp Sandbox sendet nur ihre drei vorgegebenen Templates: disclaimer, first_welcome_messsage und interactive_template_sandbox. Templates lassen sich dort weder erstellen noch bearbeiten. Wer die eigenen Template-Texte, Buttons oder Medien-Kopfzeilen eines Unternehmens testen will, braucht eine Live-Nummer, auf der jedes Template vor dem ersten Versand freigegeben wird.
Was ist eine Business-Scoped User ID in der WhatsApp Sandbox?
Eine Business-Scoped User ID (BSUID) ist die Kennung, die WhatsApp für eine Person innerhalb eines bestimmten Unternehmens verwendet, wenn diese Person ihre Telefonnummer nicht teilt. In der Sandbox ist ein Key, der ohne geteilte Nummer ausgegeben wurde, an eine BSUID gebunden. Jede Anfrage von diesem Konto nennt die BSUID im Feld recipient, und Webhook-Events identifizieren den Tester darüber.
Unterstützt die WhatsApp Sandbox Mediennachrichten?
Die WhatsApp Sandbox unterstützt weder das Hochladen noch das Abrufen von Mediendateien per Medien-ID. Tests mit Bildern, Videos und Dokumenten, die auf hochgeladene Medien angewiesen sind, brauchen eine Live-Nummer. Dort lädt die produktive API Medien per Medien-ID hoch, ruft sie ab und löscht sie, und hochgeladene Dateien bleiben 30 Tage nach ihrer letzten Nutzung gespeichert.
Quellen
[1] 360Dialog Docs, „Sandbox,“ https://docs.360dialog.com/docs/get-started/sandbox (accessed October 29, 2026).
[2] 360Dialog Docs, „Send and Receive Messages,“ https://docs.360dialog.com/docs/guides/send-and-receive-messages (accessed October 29, 2026).
[3] 360Dialog Docs, „Upload, Retrieve or Delete Media,“ https://docs.360dialog.com/docs/messaging/media/upload-retrieve-or-delete-media (accessed October 29, 2026).
[4] Meta for Developers, „Embedded Signup,“ section „555 business phone numbers,“ https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/overview#555-business-phone-numbers (updated October 27, 2026; accessed October 29, 2026).
[5] 360Dialog Docs, „Meta Provided (555) Phone Numbers,“ https://docs.360dialog.com/docs/resources/phone-numbers/meta-provided-555-phone-numbers (accessed October 29, 2026).
[6] Meta for Developers, „Updates to WhatsApp Business accounts,“ https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/ (updated September 22, 2026; accessed October 29, 2026).
[7] 360Dialog Docs, „API Key,“ https://docs.360dialog.com/docs/hub/api-key (accessed October 29, 2026).
[8] 360Dialog Docs, „Webhook,“ https://docs.360dialog.com/docs/messaging/webhook (accessed October 29, 2026).
[9] 360Dialog Docs, „Overview,“ https://docs.360dialog.com/docs (accessed October 29, 2026).
