WhatsApp API Dokumentation

Vollständige Referenz der WhatsApp-REST-API: Authentifizierung, Endpunkte, Webhooks, Fehlercodes und Codebeispiele.

Authentifizierung

Alle API-Anfragen benötigen einen API-Schlüssel im Authorization-Header. Ihr API-Schlüssel wird beim Erstellen einer Instanz generiert und ist in Ihrem Dashboard zu finden.

Authorization: Bearer YOUR_API_KEY

Anfragen ohne gültigen API-Schlüssel geben den Fehler 401 Unauthorized zurück. API-Schlüssel sind an Instanzen gebunden — jede Instanz hat ihren eigenen Schlüssel.

Basis-URL

https://api2whats.com

Alle Endpunkte sind relativ zu dieser Basis-URL. Verwenden Sie ausschließlich HTTPS — HTTP-Anfragen werden abgelehnt.

Textnachricht senden

Senden Sie eine Textnachricht an eine WhatsApp-Nummer.

POST /send-text

Anfrage-Body:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

Parameter:

  • to (string, erforderlich) — Telefonnummer des Empfängers mit Ländercode, ohne + oder Leerzeichen
  • message (string, erforderlich) — Textinhalt, unterstützt Unicode und Emoji

Antwort:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

Bild senden

Senden Sie ein Bild per URL oder Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

Parameter:

  • to (string, erforderlich) — Telefonnummer des Empfängers
  • image (string, erforderlich) — Bild-URL oder Base64-kodierter String
  • caption (string, optional) — Bildunterschrift unter dem Bild

Video senden

Senden Sie eine Videodatei.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

Audio senden

Senden Sie eine Audiodatei (Sprachnachricht oder Audioclip).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

Sticker senden

Senden Sie ein Sticker-Bild (Format WebP oder PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

Dokument senden

Senden Sie einen Dateianhang (PDF, DOCX, XLSX usw.).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

Parameter:

  • to (string, erforderlich) — Telefonnummer des Empfängers
  • document (string, erforderlich) — Dokument-URL oder Base64-kodierter String
  • filename (string, optional) — Angezeigter Dateiname (standardmäßig der Dateiname aus der URL)

Standort senden

Senden Sie einen geografischen Standort.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Webhook-Konfiguration

Webhooks ermöglichen Ihrem Server, eingehende Nachrichten in Echtzeit zu empfangen. Legen Sie Ihre Webhook-URL über die API fest:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

Wenn jemand eine Nachricht an Ihre verbundene Nummer sendet, schickt die API eine POST-Anfrage an Ihre URL:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Überprüfen Sie eingehende Webhooks anhand des X-Signature-Headers, der jeder Anfrage beiliegt.

Instanzverwaltung

Prüfen Sie den Verbindungsstatus Ihrer WhatsApp-Instanz:

GET /instance/status

Antwort:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

Fehlercodes

HTTP-CodeFehlercodeBeschreibung
400INVALID_PHONEFormat der Telefonnummer ist ungültig
400MISSING_FIELDErforderliches Feld fehlt in der Anfrage
401INVALID_API_KEYAPI-Schlüssel ist ungültig oder fehlt
404INSTANCE_NOT_FOUNDInstanz existiert nicht oder ist nicht verbunden
429RATE_LIMIT_EXCEEDEDZu viele Anfragen, prüfen Sie den Retry-After-Header
500INTERNAL_ERRORServerfehler, Wiederholung mit exponentiellem Backoff

Ratenbegrenzungen

Die Ratenbegrenzungen variieren je nach Plan:

  • Basic — 100 Anfragen/Minute
  • Professional — 300 Anfragen/Minute
  • Enterprise — 1000 Anfragen/Minute

Bei Überschreitung der Ratenbegrenzung gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück, der angibt, wann Sie es erneut versuchen können.

Codebeispiele

Funktionierende Beispiele in PHP, Python, JavaScript und cURL finden Sie in unserem Codebeispiele-Bereich. Jedes Beispiel ist ein vollständiges, ausführbares Skript.

Paginierung und Limits

Beim Auflisten von Ressourcen (Instanzen, Nachrichtenverlauf) unterstützt die API Paginierung über Query-Parameter:

GET /messages?page=1&limit=50

Antwort:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

Die Standardseitengröße ist 50, das Maximum 100. Navigieren Sie mit den Query-Parametern page und limit durch die Ergebnisse.

Sammelversand

Senden Sie Nachrichten an mehrere Empfänger in einem einzigen API-Aufruf. Das ist effizienter als einzelne Anfragen pro Empfänger.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

Der Sammelversand wendet die Ratenbegrenzung automatisch an. Die Antwort enthält den Status pro Nachricht, sodass Sie sehen, welche Nachrichten erfolgreich waren und welche fehlgeschlagen sind.

Richtlinien für Medien-Uploads

Beachten Sie beim Senden von Medien diese Richtlinien für eine optimale Zustellung:

  • Images — JPEG oder PNG, max. 5 MB via Base64, größere per URL. Empfohlene Abmessungen: 1200x630 im Querformat, 600x600 im Quadrat.
  • Videos — MP4-Format, max. 16 MB. H.264-Kodierung wird für beste Kompatibilität empfohlen.
  • Documents — PDF, DOCX, XLSX, PPTX, TXT. Max. 100 MB per URL.
  • Audio — MP3- oder OGG-Format. Max. 16 MB.
  • Stickers — WebP oder PNG, 512x512 Pixel, max. 500 KB.
  • Locations — Breiten-/Längengrad-Koordinaten mit optionalem Namen und Adresse.

Fügen Sie bei Base64-Kodierung den Data-URI-Präfix hinzu: data:image/jpeg;base64,/9j/4AAQ.... Stellen Sie bei URLs sicher, dass sie öffentlich zugänglich sind und den richtigen Content-Type-Header zurückgeben.

Umgebungsvariablen

Speichern Sie Ihren API-Schlüssel und Ihre Konfiguration in Umgebungsvariablen, nicht im Code:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

Committen Sie Ihre .env-Datei niemals in die Versionsverwaltung. Fügen Sie sie zu .gitignore hinzu. Nutzen Sie in der Produktion die Einstellungen für Umgebungsvariablen Ihrer Deployment-Plattform.

Versionierung

Die API wird über den URL-Pfad versioniert. Die aktuelle Version ist v1 (Standard). Bei grundlegenden Änderungen veröffentlichen wir eine neue Version und pflegen die alte mindestens 12 Monate weiter.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

Änderungsprotokoll

Wir führen ein öffentliches Änderungsprotokoll für alle API-Änderungen. Abonnieren Sie den RSS-Feed oder folgen Sie uns auf GitHub, um aktuell zu bleiben. Wesentliche Änderungen werden allen registrierten Benutzern mindestens 30 Tage vor der Einführung per E-Mail angekündigt.

Brauchen Sie Hilfe?

Schauen Sie in die FAQ für häufige Fragen. Bei speziellen Anliegen kontaktieren Sie unser Support-Team. Wir antworten innerhalb von 24 Stunden.

FAQ

Wie lang darf eine Nachricht maximal sein?

Textnachrichten unterstützen bis zu 4.096 Zeichen. Bei längeren Inhalten senden Sie stattdessen ein Dokument oder teilen die Nachricht auf mehrere Sendungen auf.

Kann ich Nachrichten an Gruppen senden?

Derzeit unterstützt die API nur Einzelgespräche. GruppenNachrichten sind für ein zukünftiges Release geplant.

Wie schnell werden Nachrichten zugestellt?

Die meisten Nachrichten werden innerhalb von 1–3 Sekunden zugestellt. Die Zustellzeit hängt von der Netzverbindung und dem Gerätestatus des Empfängers ab. Nachrichten an Offline-Geräte werden von WhatsApp in die Warteschlange gestellt und zugestellt, sobald das Gerät online geht.

Gibt es eine kostenlose Stufe?

Sie können kostenlos ein Konto erstellen und das Dashboard erkunden. Bezahlte Pläne beginnen ab 9,99 USD/Monat für API-Zugang und Nachrichtenversand. Kontaktieren Sie uns für Testzugang.

Was passiert, wenn mein API-Schlüssel kompromittiert wird?

Widerrufen Sie den kompromittierten Schlüssel sofort in Ihrem Dashboard und erstellen Sie einen neuen. Alle aktiven Sitzungen mit dem alten Schlüssel werden beendet. Wir empfehlen, API-Schlüssel regelmäßig zu rotieren und in Umgebungsvariablen zu speichern.

Kann ich die API für Massennachrichten nutzen?

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

Statusseite

Prüfen Sie Systemstatus und historische Verfügbarkeit auf unserer Statusseite. Während Störungen liefern wir Echtzeit-Updates und veröffentlichen ausführliche Analysen zu allen Dienstunterbrechungen.

Bereit zur Integration?

Erstellen Sie ein Konto und senden Sie in wenigen Minuten Ihre ersten Nachrichten.

Kostenlos starten