L'essentiel de ce que l'on demande à une API WhatsApp se résume à quatre choses : envoyer un message, consulter une information, modifier un enregistrement, et être prévenu quand quelque chose s'est produit. Spun expose les quatre en HTTP simple, sur le même numéro que celui auquel votre équipe répond dans la boîte de réception, avec une clé que vous créez vous-même et dont vous limitez la portée à exactement ce dont l'intégration a besoin.
Cette page en est la version pratique : quels sont les endpoints, comment fonctionnent l'authentification et les portées, ce qui se passe quand votre ligne WhatsApp est hors ligne au moment de votre appel, et où se trouve le contrat lisible par machine.
Clés, portées et étendue des dégâts en cas de fuite
L'authentification repose sur un jeton Bearer. Vous créez une clé dans l'application, elle ne vous est affichée qu'une fois, et chaque requête la transmet dans un en-tête Authorization. Spun ne stocke qu'une empreinte de la clé : une clé perdue ne peut donc pas être récupérée, seulement remplacée.
La partie qui mérite une minute d'attention, ce sont les portées. Une clé n'est pas simplement un « accès au compte » : elle porte une liste de portées, et chaque endpoint vérifie la portée précise dont il a besoin. Une clé qui n'a que read_contacts ne peut pas envoyer de message. Une clé qui n'a que send_message ne peut pas parcourir votre liste de contacts. En plus des portées, une clé peut avoir une date d'expiration et une liste d'IP autorisées, si bien qu'une clé émise pour un serveur à adresse fixe cesse de fonctionner dès qu'elle est utilisée depuis n'importe où ailleurs.
- send_message couvre l'envoi de texte et de médias, ainsi que la consultation d'un envoi mis en file d'attente.
- read_contacts, read_messages et read_labels forment le volet lecture, chacun pouvant être accordé séparément.
- manage_contacts et manage_labels couvrent la création, la mise à jour et l'étiquetage.
- check_phone indique si un numéro est joignable sur WhatsApp.
- manage_webhooks crée, liste et supprime les abonnements webhook.
Requête
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'Réponse
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}Les clés créées pour le serveur MCP de Spun sont volontairement refusées sur cette API, même lorsque ce sont des clés valides. Les deux surfaces n'ont pas la même logique d'approbation, et une clé émise pour l'une n'est pas utilisable en silence sur l'autre.
À lire aussi : Connecter un assistant IA plutôt que d'écrire du code
Ce que couvrent réellement les endpoints de l'API WhatsApp
La surface est volontairement réduite et stable, plutôt qu'un miroir exhaustif du produit. Elle existe pour qu'un système externe puisse faire ce dont les systèmes externes ont réellement besoin.
- Envoi : un message texte, ou un média sous forme d'URL ou de base64, avec une légende facultative.
- Contacts : créer un contact, le mettre à jour, et lister les contacts avec une pagination par curseur.
- Étiquettes : lister les étiquettes de l'espace de travail, en appliquer une à une conversation, en retirer une.
- Messages : lister les messages avec une pagination par curseur, pour les synchroniser vers un entrepôt de données ou un CRM.
- Vérification de numéro : confirmer qu'un numéro est sur WhatsApp avant de construire une liste autour de lui.
- File d'attente : consulter un envoi mis en file d'attente parce que la ligne était hors ligne.
- Webhooks : créer, lister et supprimer des abonnements.
Le contrat lisible par machine est publié à l'adresse /api/integrations/openapi.json et se lit sans clé : l'auteur d'un nœud n8n, le développeur d'une application Zapier ou votre propre générateur peut ainsi récupérer la spécification avant que quiconque lui ait délivré des identifiants.
Ce qui se passe quand la ligne WhatsApp est hors ligne
C'est la partie qui surprend, alors autant être explicite. Spun envoie par une session WhatsApp active, et une session active peut être coupée à la seconde précise où votre code appelle. L'API ne prétend pas le contraire, et elle se comporte volontairement de façon différente pour le texte et pour les médias.
Un envoi de texte vers une ligne hors ligne renvoie 202 plutôt qu'une erreur, avec un identifiant de file d'attente. Le message est conservé et remis quand la ligne se reconnecte, et vous pouvez interroger l'endpoint de file d'attente pour connaître son sort. Un envoi de média vers une ligne hors ligne renvoie au contraire un conflit, et n'envoie rien. Cette asymétrie est délibérée : la file d'attente écoule les messages sous forme de texte, si bien qu'une image mise en file arriverait comme une légende sans image. Échouer de façon visible est la meilleure issue, et c'est votre logique de nouvelle tentative qui décide.
La limite est de 60 requêtes par minute et par clé, avec les en-têtes standard de limitation de débit sur chaque réponse, pour qu'un client puisse ralentir en se fiant aux en-têtes plutôt qu'à un 429 inattendu.
Webhooks : être prévenu plutôt qu'interroger
Interroger un endpoint de messages à intervalles réguliers ne convient pas à une conversation, alors l'API peut pousser les événements à la place. Vous enregistrez une URL et les événements qui vous intéressent, et Spun y envoie un corps JSON au moment où ils se produisent.
Chaque livraison porte dans ses en-têtes le nom de l'événement et un identifiant de livraison unique et, lorsque l'abonnement a un secret de signature, une signature HMAC-SHA256 du corps exact. Vérifiez la signature avant de faire confiance au contenu : c'est la seule chose qui sépare votre endpoint de quiconque apprend l'URL. Le secret est renvoyé une seule fois, à la création de l'abonnement, et plus jamais ensuite.
- Événements de message, entrants et sortants.
- Contact créé, mis à jour et supprimé.
- Étiquette attribuée.
- Flux de chat terminé, envoi en file d'attente traité, prospect qualifié.
- Conversation clôturée, appel terminé et étape du pipeline modifiée.
À lire aussi : Connecter Spun à Zapier et Make · Connecter Spun à n8n · Connecter un logiciel de support : Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira
Limites et réserves honnêtes
- Ce n'est pas l'API WhatsApp Business. C'est l'API propre de Spun, placée devant votre numéro lié : il n'y a donc ni modèle de message à faire valider ni frais par message, mais pas non plus de garanties officielles de Meta.
- Soixante requêtes par minute et par clé. Les traitements en grand volume relèvent des campagnes, qui règlent correctement leur propre rythme, et non d'une boucle d'API serrée.
- La liste d'endpoints ci-dessus constitue toute la surface aujourd'hui. Ce qui n'y figure pas n'est pas exposé, et il ne faut s'appuyer sur aucun endpoint non documenté.
- Une clé a des portées, mais elle n'est pas propre à un utilisateur. Traitez-la comme des identifiants de l'espace de travail et renouvelez-la quand une personne qui y avait accès s'en va.
- Écrire à des personnes qui n'ont jamais donné leur accord fera limiter le numéro par WhatsApp, quelle que soit la voie empruntée par le message.
À lire aussi : Comment Spun se connecte à WhatsApp