Fonctionnalité

Une API WhatsApp sur le numéro que vous utilisez déjà

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"
}
Envoi d'un message. La clé d'idempotence est facultative ; répétez le même appel avec la même clé et vous récupérez l'identifiant du message d'origine au lieu d'un second envoi.

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

Questions fréquentes

Ai-je besoin de l'API WhatsApp Business pour l'utiliser ?

Non. Il s'agit de l'API REST propre de Spun, placée devant le numéro que vous avez lié par scan QR. Il n'y a ni application Meta, ni file de validation des modèles, ni facturation par message.

Comment obtenir une clé API ?

Un responsable du compte en crée une dans l'application, choisit ses portées et peut, s'il le souhaite, fixer une date d'expiration et une liste d'IP autorisées. La clé brute n'est affichée qu'une fois, à sa création ; Spun n'en conserve ensuite qu'une empreinte.

Existe-t-il une spécification OpenAPI ?

Oui, publiée à l'adresse /api/integrations/openapi.json, et lisible sans clé, pour que les outils puissent générer un client avant même que des identifiants existent.

Que se passe-t-il si j'envoie deux fois la même requête ?

Transmettez une clé d'idempotence. Un nouvel appel avec la même clé renvoie l'identifiant du message d'origine et marque la réponse comme idempotente au lieu d'envoyer un second message. Sans clé, deux appels font deux messages.

Comment vérifier qu'un webhook vient bien de Spun ?

Donnez un secret de signature à l'abonnement et contrôlez l'en-tête de signature, qui est un HMAC-SHA256 du corps brut de la requête, sous la forme sha256 suivi du condensé hexadécimal. Comparez-le à votre propre calcul sur les octets exacts que vous avez reçus, avant toute analyse du contenu.

Construisez sur le numéro auquel vos clients écrivent déjà

Des clés à portées, une surface réduite et stable, des webhooks qui vous préviennent au lieu de vous faire interroger, et aucun compteur par message.

Commencez gratuitement : 7 jours avec tout inclus

Toutes les fonctionnalités de Spun