# 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](https://support.watbot.org/de/account/profile#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](https://support.watbot.org/de/api/account#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 `GET` und `POST`; welche genau, steht bei der Methode. Methoden, die Daten ändern, rufen Sie besser mit `POST` auf.
- `POST`-Parameter werden als JSON (`Content-Type: application/json`) oder als Formularfelder übergeben, `GET`-Parameter in der URL.
- Antworten sind JSON in UTF-8.

> [!IMPORTANT]
> Senden Sie bei jeder Anfrage den Header `Accept: application/json` mit. Ohne ihn kommen Validierungsfehler nicht als JSON-Antwort `422`, sondern als Weiterleitung — Ihr Code kann solche Fehler dann nicht auswerten.

Beispiel: die Kontakte eines Bots.

```bash title="Anfrage"
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 Header `Retry-After` gibt an, nach wie vielen Sekunden Sie es erneut versuchen können; `X-RateLimit-Remaining` zeigt 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:

```json
{
  "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.