API de messagerie
API de statut des messages
Vérifiez si un message envoyé via l'API est toujours en file d'attente, a été envoyé ou a échoué. Utilisez-la pour confirmer que des messages importants sont bien partis et pour comprendre pourquoi l'un d'eux ne l'a pas été.
https://wbiztool.com/api/v1/message/status/{msg_id}/Corps: JSON ou champs de formulaire
Placez l'ID du message dans l'URL, en remplaçant {msg_id} par le msg_id renvoyé par Envoyer un message, Envoyer à un groupe, Envoyer à plusieurs numéros ou Planifier un message. Par exemple : https://wbiztool.com/api/v1/message/status/9817263/.
Exemple rapide#
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'];
}Remplacez 12345 et YOUR_API_KEY par vos propres valeurs. Consultez Authentification pour savoir où les trouver.
Paramètres de la requête#
URL
msg_idintegerobligatoireL'ID du message, dans le chemin de l'URL. Il doit s'agir d'un nombre entier appartenant à l'espace de travail de votre clé API.
Corps
client_idintegerobligatoireVotre ID client API, dans Paramètres → Clés API.
api_keystringobligatoireVotre clé API, sur cette même page.
Utiliser le client officiel#
Le client Python appelle cet endpoint pour vous.
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"))Le client renvoie les mêmes champs que l'API : result["status"] est donc l'état du message, et non un indicateur de succès. Les erreurs d'authentification lèvent requests.HTTPError ; lisez la raison avec e.response.json()["message"].
Réponse#
L'endpoint renvoie le code HTTP 200 avec l'état actuel du message :
{
"message": "Sent",
"status": 1,
"status_text": "Sent",
"error": ""
}
Un message en échec :
{
"message": "Failed",
"status": 2,
"status_text": "Failed",
"error": "Phone number invalid"
}
| Champ | Type | Description |
|---|---|---|
status | integer | Le code de statut du message. Consultez le tableau ci-dessous. |
status_text | string | Nom du statut : Created, Sent, Failed, Cancelled ou Expired. |
message | string | Même valeur que status_text. |
error | string or null | La raison de l'échec du message. Toujours présent ; vide ("" ou null) en l'absence d'erreur. |
Valeurs de statut#
status | status_text | Signification |
|---|---|---|
0 | Created | En file d'attente ou planifié, en attente d'envoi. |
1 | Sent | Envoyé depuis votre numéro WhatsApp. |
2 | Failed | N'a pas pu être envoyé, ou l'envoi a été interrompu. error en indique la raison. Si error vaut Sending was interrupted and may have been delivered. Check WhatsApp before resending., le destinataire a peut-être déjà reçu le message : ne le renvoyez donc pas automatiquement. |
3 | Cancelled | Annulé avant d'être envoyé, par exemple avec Annuler un message. |
4 | Expired | Non envoyé avant son délai expire_after_seconds. |
Sent est l'état final de réussite. Cet endpoint n'indique pas si le message a été remis sur le téléphone ni s'il a été lu.
Exemples de valeurs de error pour les messages en échec : 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.
Erreurs#
{
"message": "Unknown message id",
"status": 0,
"status_text": "pending",
"error": "Invalid message id"
}
| Message | Comment corriger |
|---|---|
Unknown message id | Aucun message avec cet ID n'existe dans l'espace de travail de votre clé API. Vérifiez l'ID et assurez-vous d'utiliser une clé du même espace de travail. |
Auth Error | Envoyez à la fois client_id et api_key. Un corps JSON invalide (par exemple avec une virgule finale) renvoie aussi Auth Error. |
Invalid Client Id | Envoyez client_id sous forme de nombre. Renvoyé avec le code HTTP 403. |
Auth Error: invalid api key | Vérifiez que la clé existe, n'a pas été supprimée et appartient à ce client_id. Renvoyé avec le code HTTP 400. |
Conseils#
- Privilégiez les webhooks pour les mises à jour en temps réel : transmettez
webhooklors de l'envoi du message, et Wbiztool vous prévient lorsqu'il est envoyé ou échoue, sans que vous ayez à interroger l'API. Les messages annulés et expirés ne déclenchent pas de webhook : vérifiez-les donc ici. - Interrogation régulière : si vous interrogez l'API, arrêtez dès que
statusne vaut plus0. Laissez quelques secondes entre deux vérifications. - Nombreux messages à la fois : pour vérifier les messages de toute une journée, utilisez Historique des messages au lieu d'appeler cet endpoint pour chaque ID.
- Les anciens messages sont purgés : les messages envoyés, en échec, annulés et expirés sans modification depuis environ 90 jours renvoient
Unknown message id. C'est aussi le cas des messages toujours en file d'attente 90 jours après leur création ou leur date programmée, sur un numéro déconnecté ou supprimé. - Anciennes intégrations :
POST /api/v1/msg_status/avecmsg_iddans le corps est obsolète. Il renvoie les mêmes champs. Il accepte aussiGETavecclient_id,api_keyetmsg_iddans la chaîne de requête, ce qui expose votre clé API dans les URL et les journaux. Passez à cet endpoint.
