API
Mit der API arbeiten Sie aus Ihrem eigenen Code mit Watbot-Bots: Kontakte finden und anlegen, ihnen Nachrichten senden, Variablen und Tags ändern, Guthaben aufladen, Listen pflegen. So kann zum Beispiel das CRM Ihrer Website eine Anfrage an den Bot übergeben oder ein Zahlungsdienst nach dem Kauf Bonuspunkte gutschreiben.
Die API steht dem Kontoinhaber mit dem Pro-Tarif zur Verfügung. Jede Anfrage wird im Namen des Schlüsselinhabers und mit dessen Rechten ausgeführt.
API-Schlüssel
Den Schlüssel erhalten Sie im Profil im Tab „API“ — Details unter API-Schlüssel. Der Schlüssel gewährt vollen Zugriff auf das Konto: Bewahren Sie ihn auf dem Server auf und fügen Sie ihn niemals in den Code von Webseiten oder mobilen Apps ein.
Der Schlüssel wird im Header Authorization übergeben:
Authorization: Bearer IHR_API_SCHLÜSSEL
Wenn Sie keinen Header setzen können, übergeben Sie den Schlüssel als Parameter api_token — in der URL oder im Anfragetext. Der Header ist sicherer: URLs mit Parametern landen in Serverprotokollen.
Der Button „Neu erstellen“ im Profil ersetzt den Schlüssel, der bisherige ist sofort ungültig. Auch beim Ändern oder Zurücksetzen des Passworts wird der Schlüssel zurückgesetzt — holen Sie sich danach einen neuen. Einen Schlüssel prüfen Sie mit der Methode getMe: Sie gibt das Konto zurück, dem der Schlüssel gehört.
Anfragen
Alle Methoden sind erreichbar unter:
https://watbot.org/de/api/v1/methodenName
- Die meisten Methoden akzeptieren
GETundPOST; welche genau, steht bei der Methode. Methoden, die Daten ändern, rufen Sie besser mitPOSTauf. POST-Parameter werden als JSON (Content-Type: application/json) oder als Formularfelder übergeben,GET-Parameter in der URL.- Antworten sind JSON in UTF-8.
Wichtig
Senden Sie bei jeder Anfrage den Header
Accept: application/jsonmit. Ohne ihn kommen Validierungsfehler nicht als JSON-Antwort422, sondern als Weiterleitung — Ihr Code kann solche Fehler dann nicht auswerten.
Beispiel: die Kontakte eines Bots.
curl -X POST "https://watbot.org/de/api/v1/getContacts" \
-H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"bot_id": 12345}'
Die Bot-ID (bot_id) ist die Zahl in der Adresse des Bots im Dashboard: /bots/12345/….
Limits
- Häufigkeit — 120 Anfragen pro Minute und Konto, alle Methoden zusammen.
- Über dem Limit antwortet die API mit
429. Der HeaderRetry-Aftergibt an, nach wie vielen Sekunden Sie es erneut versuchen können;X-RateLimit-Remainingzeigt die verbleibenden Anfragen der laufenden Minute.
Fehler
Eine erfolgreiche Antwort hat den Code 200 oder 201. Fehler:
| Code | Wann | Antwort |
|---|---|---|
401 |
Kein Schlüssel, falscher Schlüssel oder Schlüssel neu erstellt | {"error": "unauthorized"} |
402 |
Der Schlüsselinhaber hat keinen Pro-Tarif | {"error": "…", "code": "pro_required"} |
403 |
Kein Zugriff auf den Bot oder das Objekt; Konto gesperrt | {"error": "…"} |
404 |
Bot, Kontakt oder Eintrag nicht gefunden | {"error": "…"} oder {"message": "…"} |
410 |
Die Methode ist abgeschaltet (veraltete Methode nach ihrem Abschaltdatum) | {"error": "…", "code": "method_removed"} |
422 |
Parameter haben die Prüfung nicht bestanden | {"message": "…", "errors": {"feld": ["…"]}} |
429 |
Zu viele Anfragen | {"message": "Too Many Attempts."} |
Ein 422-Fehler listet in errors jedes Feld mit den Gründen auf:
{
"message": "The contact id field is required.",
"errors": {
"contact_id": ["The contact id field is required."]
}
}
Fehlertexte können sich ändern — stützen Sie sich im Code auf den Statuscode und die Felder code und errors.
Bis zur Abschaltung funktioniert eine veraltete Methode wie bisher, jede Antwort enthält aber den Header Deprecation: true und einen Header Sunset mit dem Abschaltdatum. Prüfen Sie diese in Ihrem Code, um rechtzeitig auf den Ersatz umzusteigen.