Documentation de l'API
Tout ce qu'il faut pour envoyer des messages WhatsApp depuis vos systèmes.
Premiers pas
- Créez votre compte et associez votre WhatsApp dans Mes numéros.
- Dans Clés API, créez une clé. Conservez-la : elle n'est affichée qu'une fois.
- 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ètre | Obligatoire | Description |
|---|---|---|
apikey | Oui | Votre clé. Dans l'API REST, elle va dans l'en-tête Authorization: Bearer. |
phone ou to | Non | Destinataire. Sans lui, le message arrive sur votre propre numéro : idéal pour les alertes internes. recipient est aussi accepté. |
group | Non | ID d'un groupe WhatsApp au lieu d'un numéro. Voir Groupes. |
from | Non | Numéro expéditeur si vous en avez plusieurs : son ID, son nom ou le numéro. Sans lui, le principal est utilisé. |
text | Oui, sauf avec un fichier | Texte du message, jusqu'à 4 000 caractères. Emojis et mise en forme WhatsApp acceptés : *gras*, _italique_. |
file | Non | Lien public vers une image, un PDF, une vidéo ou un audio. Le texte sert de légende. |
format | Non | Avec json, le lien simple répond en JSON au lieu de texte. |
lang | Non | Langue 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}
| Code | Signification | Que faire |
|---|---|---|
| 400 | Texte manquant, numéro invalide ou expéditeur inconnu | Vérifiez les paramètres |
| 401 | Clé erronée ou supprimée | Créez une nouvelle clé dans votre espace |
| 402 | L'essai gratuit est terminé | Choisissez une offre dans votre espace |
| 403 | Compte désactivé, ou clé du bot utilisée pour un autre destinataire | Contactez le support |
| 429 | Trop de requêtes par minute ou limite quotidienne atteinte | Patientez, 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
- Messages par jour : selon votre offre. Vous le voyez sur l'accueil de votre espace.
- Requêtes : jusqu'à 30 par minute et par clé.
- Les messages d'un même numéro sont espacés de quelques secondes pour que WhatsApp ne les considère pas comme du spam.
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'})