Aller au contenu
Wbiztool

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é.

POSThttps://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"
  }'

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_idintegerobligatoire

L'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_idintegerobligatoire

Votre ID client API, dans Paramètres → Clés API.

api_keystringobligatoire

Votre clé API, sur cette même page.

Utiliser le client officiel#

Le client Python appelle cet endpoint pour vous.

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"))

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"
}
ChampTypeDescription
statusintegerLe code de statut du message. Consultez le tableau ci-dessous.
status_textstringNom du statut : Created, Sent, Failed, Cancelled ou Expired.
messagestringMême valeur que status_text.
errorstring or nullLa raison de l'échec du message. Toujours présent ; vide ("" ou null) en l'absence d'erreur.

Valeurs de statut#

statusstatus_textSignification
0CreatedEn file d'attente ou planifié, en attente d'envoi.
1SentEnvoyé depuis votre numéro WhatsApp.
2FailedN'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.
3CancelledAnnulé avant d'être envoyé, par exemple avec Annuler un message.
4ExpiredNon 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"
}
MessageComment corriger
Unknown message idAucun 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 ErrorEnvoyez à la fois client_id et api_key. Un corps JSON invalide (par exemple avec une virgule finale) renvoie aussi Auth Error.
Invalid Client IdEnvoyez client_id sous forme de nombre. Renvoyé avec le code HTTP 403.
Auth Error: invalid api keyVé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 webhook lors 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 status ne vaut plus 0. 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/ avec msg_id dans le corps est obsolète. Il renvoie les mêmes champs. Il accepte aussi GET avec client_id, api_key et msg_id dans la chaîne de requête, ce qui expose votre clé API dans les URL et les journaux. Passez à cet endpoint.