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. Das Szenario des Bots startet sie nicht.

sendMessage#

Sendet einem Kontakt Text, ein Bild oder eine Datei.

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.

Was Sie in contact_external_id übergeben:

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 liefern sie.

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

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."}'

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"
  }'

{
  "success": true
}

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

Fehler der Methode (allgemeine unter Fehler):

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

sendMessageToQueue#

Achtung

Diese Methode ist veraltet und wird am 1. Dezember 2026 abgeschaltet — verwenden Sie stattdessen 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.

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.

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."}'

{
  "error": "Kontakt nicht gefunden"
}

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