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.
https://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"
}'import requests
msg_id = 9817263
response = requests.post(
f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") == "Unknown message id":
print("No message with this ID in your workspace")
elif "status_text" not in result:
print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
print("Sent")
elif result["status"] == 2:
print("Failed:", result["error"])
else:
print("Status:", result["status_text"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message === "Unknown message id") {
console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
console.log("Sent");
} else if (result.status === 2) {
console.log("Failed:", result.error);
} else {
console.log("Status:", result.status_text);
}<?php
$msgId = 9817263;
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
];
$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') === 'Unknown message id') {
echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
echo 'Sent';
} elseif ($result['status'] === 2) {
echo 'Failed: ' . $result['error'];
} else {
echo 'Status: ' . $result['status_text'];
}Ersetzen Sie 12345 und YOUR_API_KEY durch Ihre eigenen Werte. Wo Sie diese finden, steht unter Authentifizierung.
Request-Parameter#
URL
msg_idintegererforderlichDie Nachrichten-ID als Teil des URL-Pfads. Sie muss eine ganze Zahl sein und zum Arbeitsbereich Ihres API-Schlüssels gehören.
Body
client_idintegererforderlichIhre API-Client-ID aus Einstellungen → API-Schlüssel.
api_keystringerforderlichIhr API-Schlüssel von derselben Seite.
Offiziellen Client verwenden#
Der Python-Client ruft diesen Endpoint für Sie auf.
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"
}
| Feld | Typ | Beschreibung |
|---|---|---|
status | integer | Der Statuscode der Nachricht. Siehe Tabelle unten. |
status_text | string | Name des Status: Created, Sent, Failed, Cancelled oder Expired. |
message | string | Derselbe Wert wie status_text. |
error | string or null | Warum die Nachricht fehlgeschlagen ist. Immer vorhanden; leer ("" oder null), wenn kein Fehler vorliegt. |
Statuswerte#
status | status_text | Bedeutung |
|---|---|---|
0 | Created | In der Warteschlange oder geplant, wartet auf den Versand. |
1 | Sent | Von Ihrer WhatsApp-Nummer gesendet. |
2 | Failed | Konnte 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. |
3 | Cancelled | Vor dem Versand storniert, zum Beispiel mit Nachricht stornieren. |
4 | Expired | Nicht 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"
}
| Meldung | Lösung |
|---|---|
Unknown message id | Im 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 Error | Senden Sie client_id und api_key. Auch ein ungültiger JSON-Body (zum Beispiel mit einem abschließenden Komma) liefert Auth Error. |
Invalid Client Id | Senden Sie client_id als Zahl. Wird mit HTTP 403 zurückgegeben. |
Auth Error: invalid api key | Prü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
statusnicht mehr0ist. 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/mitmsg_idim Body ist veraltet. Es liefert dieselben Felder. Es akzeptiert auchGETmitclient_id,api_keyundmsg_idim Query-String, wodurch Ihr API-Schlüssel in URLs und Logs sichtbar wird. Wechseln Sie zu diesem Endpoint.
