# Nachrichten

Über die API kann ein Bot einem Kontakt aus Ihrem eigenen System schreiben: an einen Termin erinnern, einen Beleg schicken, aus dem CRM antworten. Dafür gibt es die Methode **sendMessage** — sie sendet Text, ein Bild oder eine Datei sofort und meldet, ob die Nachricht rausgegangen ist.

Die Methode **sendMessageToQueue** ist veraltet und wird abgeschaltet — nehmen Sie in neuen Integrationen sendMessage.

Die Nachricht wird im Dialog des Kontakts unter dem Namen „API“ gespeichert — Sie sehen sie unter [Dialoge und Schriftverkehr](https://support.watbot.org/de/chatbots/messages/dialogs). Das Szenario des Bots startet sie nicht.

## sendMessage

Sendet einem Kontakt Text, ein Bild oder eine Datei.

```endpoint
POST https://watbot.org/de/api/v1/sendMessage
```

Der Kontakt wird auf eine von zwei Arten angegeben: über die Kontakt-ID — `contact_id` — oder über Bot und Messenger-ID — `bot_id`, `messenger` und `contact_external_id` zusammen.

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Zahl | ja, ohne `messenger` | Kontakt-ID |
| `bot_id` | Zahl | ja, ohne `contact_id` | Bot-ID |
| `messenger` | String | ja, ohne `contact_id` | Messenger des Kontakts: `telegram`, `max`, `viber`, `vk` oder `web` (Chat auf der Website) |
| `contact_external_id` | String | ja, ohne `contact_id` | ID des Kontakts im Messenger, bis 255 Zeichen — siehe unten |
| `text` | String | ja, ohne `image` und `file` | Nachrichtentext. Mit Bild oder Datei wird er zur Bildunterschrift |
| `image` | String | ja, ohne `text` und `file` | Link zu einem Bild |
| `file` | String | ja, ohne `text` und `image` | Link zu einer Datei |
| `filename` | String | nein | Dateiname für den Empfänger. Umlaute und nicht-lateinische Buchstaben werden transliteriert, alle Zeichen außer Buchstaben, Ziffern, `.`, `_` und `-` durch `_` ersetzt |

Was Sie in `contact_external_id` übergeben:

| `messenger` | Wert |
|---|---|
| `telegram` | Telegram-Benutzer-ID (Feld `telegram_id` des Kontakts) oder seine Telefonnummer |
| `max` | MAX-Benutzer-ID (Feld `max_user_id`) oder Telefonnummer |
| `viber` | Viber-Benutzer-ID (Feld `viber_id`) oder Telefonnummer |
| `vk` | VK-Benutzer-ID — `700123456` (die frühere Form `vk700123456` funktioniert weiterhin) — oder Telefonnummer |
| `web` | Besucher-ID im Website-Chat |

Die Telefonnummer wird Zeichen für Zeichen mit der Nummer des Kontakts verglichen (Feld `phone` in den Antworten der Kontaktmethoden). Am zuverlässigsten ist `contact_id` — die [Kontaktmethoden](https://support.watbot.org/de/api/contacts) liefern sie.

Werden `image` und `file` zugleich übergeben, wird das Bild gesendet.

```bash title="Anfrage: Text"
curl -X POST "https://watbot.org/de/api/v1/sendMessage" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Frau Schmidt, Ihre Bestellung Nr. 1042 wurde versandt."}'
```

```bash title="Anfrage: Datei per Telegram-ID"
curl -X POST "https://watbot.org/de/api/v1/sendMessage" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "contact_external_id": "123456789",
    "file": "https://example.com/invoices/1042.pdf",
    "filename": "Rechnung 1042.pdf",
    "text": "Ihre Rechnung"
  }'
```

```json title="Antwort 200"
{
  "success": true
}
```

```json title="Antwort 404"
{
  "message": "Kontakt nicht gefunden"
}
```

**Versandlimit.** Höchstens 10 Nachrichten pro 10 Sekunden an einen Messenger. Der Zähler gilt pro Konto und für jeden Messenger getrennt: Die 10 Sekunden beginnen mit der ersten Nachricht, danach wird der Zähler zurückgesetzt. Abgelehnte Anfragen zählen nicht mit und verlängern das Zeitfenster nicht. Eine `429`-Antwort enthält den Header `Retry-After` — nach wie vielen Sekunden Sie es erneut versuchen können. Das allgemeine Anfragelimit der API gilt zusätzlich — siehe [Limits](https://support.watbot.org/de/api#limits).

Fehler der Methode (allgemeine unter [Fehler](https://support.watbot.org/de/api#fehler)):

| Code | Wann | Antwort |
|---|---|---|
| `404` | Kontakt oder Bot ist nicht unter Ihren: Diese ID gibt es nicht, sie gehört zu einem anderen Konto oder wurde gelöscht; kein Kontakt mit diesem `messenger` und dieser `contact_external_id` im Bot | `{"message": "Kontakt nicht gefunden"}` oder `{"message": "Bot nicht gefunden"}` |
| `422` | Weder `text` noch `image` noch `file`; der Link in `image` oder `file` ist keine URL; `contact_id` oder `bot_id` ist keine positive ganze Zahl | `{"message": "…", "errors": {…}}` |
| `429` | Das Versandlimit für diesen Messenger ist überschritten | `{"error": "Sendelimit für telegram erreicht"}` |
| `501` | Der Kontakt stammt aus einem Kanal, an den nicht mehr gesendet werden kann | `{"error": "Das Senden von Nachrichten an … wird nicht unterstützt"}` |

Fehlertexte kommen in der Sprache aus dem Header `Accept-Language`.

## sendMessageToQueue

> [!WARNING]
> Diese Methode ist veraltet und wird am 1. Dezember 2026 abgeschaltet — verwenden Sie stattdessen [sendMessage](https://support.watbot.org/de/api/messages#sendmessage). Bis dahin trägt jede Antwort der Methode die Header `Deprecation: true` und `Sunset: Tue, 01 Dec 2026 00:00:00 GMT`. Ab dem 1. Dezember 2026 (00:00 UTC) antwortet die Methode mit Status `410`: `{"error": "This API method was removed on 2026-12-01.", "code": "method_removed"}`.

Stellt eine Textnachricht an einen Kontakt in die Warteschlange. Die Warteschlange wird einmal pro Minute abgearbeitet.

```endpoint
POST https://watbot.org/de/api/v1/sendMessageToQueue
```

Der Kontakt wird unter den Kontakten all Ihrer Bots gesucht, mit `bot_id` nur unter den Kontakten dieses Bots. Geben Sie mindestens einen der Parameter `contact_id`, `bitrix_contact_id`, `phone` an; geben Sie mehrere an, muss der Kontakt zu allen passen. Passen zu `phone` oder `bitrix_contact_id` mehrere Kontakte und fehlt `bot_id`, wird die Nachricht für einen davon eingereiht: zuerst für einen Kontakt eines Messengers, an den die Methode senden kann, der den Bot nicht blockiert hat, dann für einen mit exakt passendem Feld `phone` (WhatsApp), dann für den mit dem jüngsten Chatverlauf. An wen die Nachricht ging, zeigen die Antwort-Header `X-Contact-Id` und `X-Contact-Ambiguous: true`. Mit `bot_id` wird nicht gewählt: Passen auch in diesem Bot mehrere Kontakte, antwortet die Methode mit `422` und reiht die Nachricht nicht ein — geben Sie `contact_id` an.

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `contact_id` | Zahl | einer von dreien | Kontakt-ID |
| `bitrix_contact_id` | Zahl | einer von dreien | ID des Bitrix24-Kontakts, mit dem der Kontakt des Bots verknüpft ist |
| `phone` | String | einer von dreien | Telefonnummer des Kontakts, bis 20 Zeichen. Leerzeichen, Klammern, Bindestriche und `+` werden entfernt, eine führende `8` wird durch `7` ersetzt |
| `bot_id` | Zahl | nein | ID des Bots, über den gesendet wird. Angeben, wenn die Nummer oder die Bitrix24-ID zu Kontakten mehrerer Ihrer Bots gehört |
| `text` | String | ja | Nachrichtentext, bis 1024 Zeichen |
| `message_id` | String | nein | Ihre eigene Nachrichten-ID, bis 255 Zeichen. Schützt vor Duplikaten: Eine wiederholte Anfrage mit derselben `message_id` an denselben Kontakt reiht die Nachricht nicht erneut ein, solange die frühere wartet oder schon gesendet ist — die Antwort ist dieselbe `201`. Nach einem Sendefehler reiht eine Wiederholung die Nachricht neu ein |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/sendMessageToQueue" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Erinnerung: Ihr Termin ist morgen um 11:00 Uhr."}'
```

```json title="Antwort 422"
{
  "error": "Kontakt nicht gefunden"
}
```

```json title="Antwort 422: contact_id nötig"
{
  "message": "Auf diese Daten passen im Bot mehrere Kontakte — geben Sie contact_id an.",
  "errors": {
    "contact_id": ["Auf diese Daten passen im Bot mehrere Kontakte — geben Sie contact_id an."]
  }
}
```

Eine erfolgreiche Antwort hat den Status `201`, einen leeren Body und die ID des gewählten Kontakts im Header `X-Contact-Id`. Die bereinigte Nummer aus `phone` muss Zeichen für Zeichen mit der Nummer des Kontakts übereinstimmen. Für einen Kontakt aus einem Kanal, an den nicht mehr gesendet werden kann, antwortet die Methode mit `422`: `{"error": "Messenger wird nicht unterstützt"}`. Kontakte, die sich vom Bot abgemeldet oder ihn blockiert haben, erhalten keine Nachrichten aus der Warteschlange — solche Nachrichten werden beim nächsten Durchlauf aus der Warteschlange genommen.