Aller au contenu
Dashboard

Messages

Envoyer un message à un lead sur WhatsApp via le moteur anti-ban, ou sur Instagram et Messenger dans la fenêtre de 24 heures, sans risque au retry.

POST /messages écrit à un lead sur son propre canal, comme si un coéquipier avait répondu dans le dashboard. Sur WhatsApp, le message part du numéro de sa campagne et les règles anti-ban sont appliquées côté serveur. Sur Instagram et Messenger, il part du compte ou de la Page, dans la fenêtre de 24 heures de Meta (plus bas).

Méthode Chemin Scope
POST /messages messages:send
Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/messages" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f" \
-d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"On se confirme pour demain 14h ?"}'
{
"data": {
"id": "66f1a2b3c4d5e6f7a8b9c0e5",
"message_id": "true_33612345678@c.us_3EB0C8F2A1D4B5E6F7A8",
"lead_id": "66f1a2b3c4d5e6f7a8b9c0d1",
"text": "On se confirme pour demain 14h ?",
"sent_at": "2026-09-19T08:12:04.000Z",
"humanized": true,
"typing_ms": 3210,
"quota": {
"limit": 250,
"used": 41,
"remaining": 209,
"resets_at": "2026-09-20T00:00:00.000Z"
}
}
}
Champ Signification
id L’id de la ligne de conversation dans WhatSetter, ou null si la ligne n’a pas pu être écrite après l’envoi.
message_id L’id du message WhatsApp.
lead_id Le lead à qui tu as écrit.
text Le texte envoyé.
sent_at Quand le moteur l’a accepté.
humanized Si la chorégraphie humaine a été jouée.
typing_ms Le délai de frappe simulé, 0 quand humanize vaut false.
quota Le budget quotidien du numéro après cet envoi.

201 signifie que le message a été accepté par le moteur WhatsApp. La livraison finale est asynchrone, comme sur toute API WhatsApp. Le message apparaît dans la conversation du dashboard comme une réponse manuelle.

Le lead doit déjà avoir une conversation : au moins un message échangé. Sinon tu reçois 409 lead_not_contacted. Le premier contact passe par une liste et une campagne ou un lead opt-in.

Chaque envoi consomme le même budget quotidien que le moteur de campagne pour ce numéro WhatsApp (250 messages par jour quand aucun quota spécifique n’est réglé). Une fois atteint : 429 quota_exceeded, remise à zéro à minuit UTC.

Chaque 201 et chaque 429 porte le budget dans les en-têtes :

X-Quota-Limit: 250
X-Quota-Remaining: 209
X-Quota-Reset: 2026-09-20T00:00:00.000Z

Si la campagne n’a pas de numéro WhatsApp, ou si le numéro est déconnecté, tu reçois 503 agent_disconnected. Vérifie whatsapp_connected sur GET /campaigns et reconnecte-le depuis le dashboard.

Par défaut (humanize: true), l’envoi rejoue une chorégraphie humaine : accusé de lecture, indicateur « en train d’écrire », un délai de frappe proportionnel à la longueur du message, puis l’envoi. Compte 3 à 15 secondes par requête. C’est le mode recommandé.

"humanize": false envoie instantanément, toujours sous quota. Réserve-le aux confirmations urgentes.

text est obligatoire, 1 à 4096 caractères, texte seulement.

Le même appel, le même corps, sur un lead dont le channel vaut instagram ou facebook (Messenger). Le message part par le chemin de la boîte de réception du dashboard et apparaît dans le fil comme une réponse manuelle.

  • Seulement dans les 24 heures qui suivent le dernier message de la personne. C’est la règle de Meta pour une entreprise. Au-delà, tu reçois 409 messaging_window_closed avec window_closes_at (l’heure où elle s’est fermée), et rien n’est envoyé : attends que la personne écrive à nouveau. WhatSetter n’utilise jamais par l’API l’étiquette qui étend la fenêtre à 7 jours ; elle est réservée à une réponse tapée par une personne dans la boîte de réception.
  • Comme une réponse tapée dans la boîte de réception, il met l’agent en pause sur ce lead pendant le human_pause_hours du compte (guide Instagram), pour qu’il ne réponde pas par-dessus toi. La réponse dit jusqu’à quand dans agent_paused_until. POST /leads/{id}/resume met fin à la pause.
  • Le texte : 1 000 caractères sur Instagram, 2 000 sur Messenger. Ni quota WhatsApp ni envoi humanisé : humanize est ignoré, quota vaut null.
{
"error": {
"code": "messaging_window_closed",
"message": "Instagram lets a business answer only within 24 hours of the person's last message. Wait for them to write again.",
"window_closes_at": "2026-10-29T18:42:10.000Z"
}
}

GET /conversations?channel=instagram&needs_reply=true liste les fils qui attendent une réponse (Conversations).

Une API de messages doit pouvoir être rejouée sans danger : un timeout ne doit jamais se transformer en second vrai message WhatsApp. Passe un en-tête Idempotency-Key à chaque envoi, unique par intention (un UUID, un id de commande…), 200 caractères maximum. WhatSetter s’en souvient 15 minutes.

Situation Ce qu’obtient un retry avec la même clé
Le premier appel a répondu 201 Le même corps 201, avec l’en-tête X-Idempotent-Replay: true. Pas de second message.
Le premier appel est encore en cours 409 request_in_flight. Attends et réessaie.
Le premier appel a échoué proprement (422, 409, 429, 503) La clé est libérée : ton retry est une vraie nouvelle tentative.
Le premier appel a expiré (502 send_failed) 409 request_in_flight jusqu’à la fin de la fenêtre : le message est peut-être parti. Vérifie la transcription avant de renvoyer.
HTTP code Quand
401 missing_api_key, invalid_api_key Clé absente, inconnue ou révoquée.
403 insufficient_scope La clé n’a pas messages:send.
404 not_found Lead inconnu, ou lead d’un autre espace de travail.
409 lead_not_contacted Le lead n’a jamais été contacté. Passe par une liste ou un lead opt-in.
409 request_in_flight Même Idempotency-Key encore en traitement, ou une tentative précédente avec cette clé a expiré.
409 messaging_window_closed Instagram ou Messenger : plus de 24 heures depuis le dernier message de la personne. Voir window_closes_at.
409 recipient_unreachable Instagram ou Messenger : la personne ne reçoit pas de messages du compte en ce moment (elle l’a bloqué, ou a coupé ses messages).
409 instagram_reconnect_required, facebook_reconnect_required, facebook_page_required, instagram_account_not_found Instagram ou Messenger : le compte ou la Page doit être reconnecté depuis le dashboard.
403 instagram_not_enabled Un lead Instagram, et Instagram n’est pas activé sur l’espace.
422 validation_error lead_id absent, text vide ou trop long, humanize qui n’est pas un booléen, clé de plus de 200 caractères.
429 quota_exceeded Budget quotidien du numéro atteint. Voir X-Quota-Reset.
429 rate_limited Trop de requêtes cette minute. Respecte Retry-After.
500 internal_error Moteur de messagerie non configuré de notre côté.
502 send_failed Le moteur a refusé ou n’a pas confirmé l’envoi. Réessaie avec la même clé.
503 agent_disconnected Pas de numéro sur la campagne, ou numéro hors ligne.