Zum Inhalt springen
Wbiztool

Messaging-API

Nachrichtenstatus (Message Status API)

Prüfen Sie, ob eine über die API gesendete Nachricht noch in der Warteschlange steht, gesendet wurde oder fehlgeschlagen ist. Nutzen Sie die API, um zu bestätigen, dass wichtige Nachrichten versendet wurden, und um herauszufinden, warum eine Nachricht nicht versendet wurde.

POSThttps://wbiztool.com/api/v1/message/status/{msg_id}/

Body: JSON oder Formularfelder

Setzen Sie die Nachrichten-ID in die URL ein und ersetzen Sie {msg_id} durch die msg_id, die Nachricht senden, An Gruppe senden, An mehrere Nummern senden oder Nachricht planen zurückgegeben hat. Zum Beispiel: https://wbiztool.com/api/v1/message/status/9817263/.

Kurzes Beispiel#

curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY"
  }'

Ersetzen Sie 12345 und YOUR_API_KEY durch Ihre eigenen Werte. Wo Sie diese finden, steht unter Authentifizierung.

Request-Parameter#

URL

msg_idintegererforderlich

Die Nachrichten-ID als Teil des URL-Pfads. Sie muss eine ganze Zahl sein und zum Arbeitsbereich Ihres API-Schlüssels gehören.

Body

client_idintegererforderlich

Ihre API-Client-ID aus Einstellungen → API-Schlüssel.

api_keystringerforderlich

Ihr API-Schlüssel von derselben Seite.

Offiziellen Client verwenden#

Der Python-Client ruft diesen Endpoint für Sie auf.

Python
from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))

Der Client gibt dieselben Felder wie die API zurück, result["status"] ist also der Zustand der Nachricht, kein Erfolgs-Flag. Authentifizierungsfehler lösen requests.HTTPError aus; den Grund lesen Sie mit e.response.json()["message"].

Antwort#

Der Endpoint gibt HTTP 200 mit dem aktuellen Zustand der Nachricht zurück:

{
  "message": "Sent",
  "status": 1,
  "status_text": "Sent",
  "error": ""
}

Eine fehlgeschlagene Nachricht:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}
FeldTypBeschreibung
statusintegerDer Statuscode der Nachricht. Siehe Tabelle unten.
status_textstringName des Status: Created, Sent, Failed, Cancelled oder Expired.
messagestringDerselbe Wert wie status_text.
errorstring or nullWarum die Nachricht fehlgeschlagen ist. Immer vorhanden; leer ("" oder null), wenn kein Fehler vorliegt.

Statuswerte#

statusstatus_textBedeutung
0CreatedIn der Warteschlange oder geplant, wartet auf den Versand.
1SentVon Ihrer WhatsApp-Nummer gesendet.
2FailedKonnte nicht gesendet werden, oder der Sendevorgang wurde unterbrochen. error nennt den Grund. Ist error gleich Sending was interrupted and may have been delivered. Check WhatsApp before resending., hat der Empfänger die Nachricht möglicherweise bereits erhalten. Senden Sie sie daher nicht automatisch erneut.
3CancelledVor dem Versand storniert, zum Beispiel mit Nachricht stornieren.
4ExpiredNicht vor Ablauf der Frist expire_after_seconds gesendet.

Sent ist der endgültige Erfolgszustand. Dieser Endpoint meldet nicht, ob die Nachricht auf dem Telefon zugestellt oder gelesen wurde.

Beispiele für error-Werte bei fehlgeschlagenen Nachrichten: Phone number invalid, Group not found, Image Url Error, File Url Error, Blocked Contact, File exceeds WhatsApp size limit (…), File type not supported, Sending was interrupted and may have been delivered. Check WhatsApp before resending.

Fehler#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}
MeldungLösung
Unknown message idIm Arbeitsbereich Ihres API-Schlüssels gibt es keine Nachricht mit dieser ID. Prüfen Sie die ID und ob Sie einen Schlüssel aus demselben Arbeitsbereich verwenden.
Auth ErrorSenden Sie client_id und api_key. Auch ein ungültiger JSON-Body (zum Beispiel mit einem abschließenden Komma) liefert Auth Error.
Invalid Client IdSenden Sie client_id als Zahl. Wird mit HTTP 403 zurückgegeben.
Auth Error: invalid api keyPrüfen Sie, ob der Schlüssel existiert, nicht gelöscht wurde und zu dieser client_id gehört. Wird mit HTTP 400 zurückgegeben.

Tipps#

  • Für Echtzeit-Updates besser Webhooks verwenden: Übergeben Sie beim Senden der Nachricht webhook, dann benachrichtigt Wbiztool Sie, sobald sie gesendet wurde oder fehlgeschlagen ist, und Sie müssen nicht regelmäßig abfragen. Stornierte und abgelaufene Nachrichten lösen keinen Webhook aus, prüfen Sie diese daher hier.
  • Polling: Wenn Sie doch regelmäßig abfragen, hören Sie auf, sobald status nicht mehr 0 ist. Lassen Sie zwischen den Abfragen einige Sekunden Abstand.
  • Viele Nachrichten auf einmal: Um die Nachrichten eines ganzen Tages zu prüfen, verwenden Sie Nachrichtenverlauf, statt diesen Endpoint für jede ID aufzurufen.
  • Alte Nachrichten werden entfernt: Gesendete, fehlgeschlagene, stornierte und abgelaufene Nachrichten, die etwa 90 Tage lang unverändert sind, liefern Unknown message id. Dasselbe gilt für Nachrichten, die 90 Tage nach ihrer Erstellung oder ihrem geplanten Zeitpunkt noch in der Warteschlange einer getrennten oder gelöschten Nummer stehen.
  • Alte Integrationen: POST /api/v1/msg_status/ mit msg_id im Body ist veraltet. Es liefert dieselben Felder. Es akzeptiert auch GET mit client_id, api_key und msg_id im Query-String, wodurch Ihr API-Schlüssel in URLs und Logs sichtbar wird. Wechseln Sie zu diesem Endpoint.