Documentation de l'API

Tout ce qu'il faut pour envoyer des messages WhatsApp depuis vos systèmes.

Premiers pas

  1. Créez votre compte et associez votre WhatsApp dans Mes numéros.
  2. Dans Clés API, créez une clé. Conservez-la : elle n'est affichée qu'une fois.
  3. Ouvrez ce lien dans le navigateur, avec votre clé. Un message vous parviendra :
/api/send?text=Bonjour&apikey=VOTRE_CLE

Envoyer un message

Il existe deux méthodes équivalentes. Utilisez celle qui vous convient.

Lien simple (GET ou POST de formulaire)

/api/send?phone=0612345678&text=Votre%20commande%20part%20aujourd'hui&apikey=VOTRE_CLE

Les paramètres peuvent figurer dans l'adresse ou dans un formulaire (application/x-www-form-urlencoded). Le service répond aussi sur /send.php.

API REST (JSON)

POST /api/v1/messages
Authorization: Bearer VOTRE_CLE
Content-Type: application/json

{ "to": "0612345678", "text": "Votre commande part aujourd'hui" }

Paramètres

ParamètreObligatoireDescription
apikeyOuiVotre clé. Dans l'API REST, elle va dans l'en-tête Authorization: Bearer.
phone ou toNonDestinataire. Sans lui, le message arrive sur votre propre numéro : idéal pour les alertes internes. recipient est aussi accepté.
groupNonID d'un groupe WhatsApp au lieu d'un numéro. Voir Groupes.
fromNonNuméro expéditeur si vous en avez plusieurs : son ID, son nom ou le numéro. Sans lui, le principal est utilisé.
textOui, sauf avec un fichierTexte du message, jusqu'à 4 000 caractères. Emojis et mise en forme WhatsApp acceptés : *gras*, _italique_.
fileNonLien public vers une image, un PDF, une vidéo ou un audio. Le texte sert de légende.
formatNonAvec json, le lien simple répond en JSON au lieu de texte.
langNonLangue des messages d'erreur : fr, es, en ou pt.

Groupes

Disponible avec l’offre Pro et supérieures, et pendant l’essai gratuit. Votre numéro doit être membre du groupe. Dans l'espace client, Mes numéros → Voir les groupes affiche chaque groupe avec son ID. Vous pouvez aussi les obtenir via l'API :

GET /api/v1/groups
Authorization: Bearer VOTRE_CLE

{"ok":true,"groups":[{"id":"120363012345678901","name":"Commerciaux","size":6}]}
/api/send?group=120363012345678901&text=Réunion%20à%2010%20h&apikey=VOTRE_CLE

En JSON, "to": "[email protected]" fonctionne aussi. Les groupes sont disponibles avec les numéros associés par QR code.

Plusieurs numéros

Si votre compte a plusieurs numéros, choisissez l'expéditeur avec from. Il accepte l'ID affiché dans l'espace client, le nom que vous lui avez donné (par exemple Atelier) ou le numéro lui-même.

/api/send?from=Atelier&phone=0612345678&text=Votre%20appareil%20est%20prêt&apikey=VOTRE_CLE

Chaque numéro a sa propre file : les envois d'un numéro n'attendent pas ceux d'un autre.

Images et documents

Ajoutez file avec un lien téléchargeable sans connexion. 16 Mo maximum.

/api/send?phone=0612345678&text=Bon%20de%20livraison%20joint&file=https://drive.google.com/file/d/ID/view&apikey=VOTRE_CLE

Les liens Google Drive de type « Tous les utilisateurs disposant du lien » sont convertis automatiquement en téléchargement direct.

Réponses de l'API

Les messages ne partent pas au moment de la requête : ils entrent dans une file et partent dans l'ordre, espacés de quelques secondes pour protéger votre numéro. La réponse confirme que le message est en attente.

Lien simple :  200  Message en file d'attente. id=123
API REST :     202  {"ok":true,"id":123,"status":"queued","to":"33612345678","from":5}
CodeSignificationQue faire
400Texte manquant, numéro invalide ou expéditeur inconnuVérifiez les paramètres
401Clé erronée ou suppriméeCréez une nouvelle clé dans votre espace
402L'essai gratuit est terminéChoisissez une offre dans votre espace
403Compte désactivé, ou clé du bot utilisée pour un autre destinataireContactez le support
429Trop de requêtes par minute ou limite quotidienne atteintePatientez, ou passez à une offre supérieure

État d'un message

GET /api/v1/messages/123
Authorization: Bearer VOTRE_CLE

{"ok":true,"message":{"id":123,"status":"sent","attempts":1,"error":null, ...}}

États : queued (en attente), sending, sent (remis à WhatsApp) et failed (non envoyé, avec la raison dans error). Si un numéro se déconnecte, ses messages attendent et sont renvoyés automatiquement.

État de vos numéros : GET /api/v1/status

Format des numéros

Les numéros de tous les pays fonctionnent. Écrivez-les au format international (+33 6 12 34 56 78, 0033…) ou au format local de votre pays (06 12 34 56 78). Sans indicatif, le pays de votre compte est utilisé ; vous pouvez le modifier dans Paramètres.

Le système connaît les règles de numérotation de chaque pays : il retire le 0 ou le préfixe national si nécessaire et ajoute l'indicatif. Par exemple, 06 12 34 56 78 en France devient +33 6 12 34 56 78 et (11) 98765-4321 au Brésil devient +55 11 98765 4321.

Limites

N'envoyez que des messages attendus par vos destinataires. Les envois massifs à des personnes qui ne vous connaissent pas peuvent conduire WhatsApp à restreindre votre numéro.

Recevoir des messages

Dans Paramètres, vous pouvez indiquer une adresse https:// de votre système. Chaque message reçu par l'un de vos numéros y sera transféré ainsi :

POST https://votre-systeme.com/webhook
Content-Type: application/json
X-Wagate-Signature: signature HMAC-SHA256 du corps

{"event":"message.received","number_id":5,"from":"+33612345678","message":"OUI","name":"Luc","group":null,"at":1762440000000}

Exemples

Google Apps Script

function envoyerWhatsApp(telephone, texte) {
  const r = UrlFetchApp.fetch('/api/send', {
    method: 'post',
    payload: { apikey: 'VOTRE_CLE', phone: telephone, text: texte },
    muteHttpExceptions: true,
  });
  return r.getResponseCode() === 200;
}

AppSheet

Automation, Bot, tâche « Call a webhook » : URL /api/v1/messages, POST, JSON, en-tête Authorization: Bearer VOTRE_CLE et corps :

{ "to": "<<[TELEPHONE]>>", "text": "Bonjour <<[CLIENT]>>, votre commande est prête." }

PHP

file_get_contents('/api/send?' . http_build_query([
  'apikey' => 'VOTRE_CLE', 'phone' => '0612345678', 'text' => 'Bonjour depuis PHP',
]));

Python

import requests
requests.post('/api/v1/messages',
  headers={'Authorization': 'Bearer VOTRE_CLE'},
  json={'to': '0612345678', 'text': 'Bonjour depuis Python'})