API WP-API

01 · Vue d'ensemble

Introduction

L'API WP-API expose une interface HTTP REST simple pour envoyer des messages WhatsApp et suivre leur statut de livraison en temps réel via des webhooks. Toutes les requêtes et réponses utilisent JSON.

02 · Sécurité

Authentification

Chaque requête doit inclure votre clé API dans l'en-tête Authorization. Générez et gérez vos clés depuis votre espace développeur.

Authorization: Bearer wp_live_VOTRE_CLE

03 · Pour commencer

Démarrage rapide

1. Créez une clé API depuis votre espace développeur
2. Connectez votre WhatsApp depuis le dashboard si ce n'est pas déjà fait
3. Envoyez votre premier message avec l'exemple ci-dessous
4. (Optionnel) Configurez un webhook pour suivre les statuts de livraison en temps réel

04 · Endpoint

Envoyer un message

Envoie un message texte, ou une image avec légende, à un numéro WhatsApp.

Paramètres

Exemple de requête

curl -X POST https://wp-api.integriscloud.com/api/v1/public/messages/send \
  -H "Authorization: Bearer wp_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "22670000000",
    "message": "Votre code de vérification est 482913"
  }'

Réponse — 200 OK

{
  "success": true,
  "messageId": "3EB09FB6BF40A3D9ABF1AD",
  "timestamp": 1783629676
}

05 · Endpoint

Vérifier un numéro

Vérifie qu'un numéro possède un compte WhatsApp actif avant de lui envoyer un message. Recommandé avant tout envoi vers un numéro dont vous n'êtes pas certain.

Exemple de requête

curl "https://wp-api.integriscloud.com/api/v1/public/numbers/22670000000/check" \
  -H "Authorization: Bearer wp_live_VOTRE_CLE"

Réponse — 200 OK

{ "phone": "22670000000", "hasWhatsapp": true }

06 · Référence

Codes d'erreur

Toute erreur renvoie un corps JSON avec un champ error (code stable, à utiliser dans votre logique applicative) et message (texte lisible, susceptible d'évoluer).

{
  "statusCode": 401,
  "error": "invalid_api_key",
  "message": "Clé API invalide ou révoquée."
}

07 · Référence

Limites de débit

60 requêtes par minute par compte, tous endpoints confondus. Au-delà, vous recevrez une erreur 429. Cette limite est actuellement appliquée par adresse IP ; une limitation par clé API est prévue.

08 · Webhooks

Vue d'ensemble

Configurez une URL depuis votre espace développeur pour recevoir, en temps réel, le statut de chaque message que vous envoyez : accepté, livré, lu, ou échoué. Un secret de signature unique est généré automatiquement à l'activation.

Votre endpoint doit répondre avec un code 2xx rapidement (moins de 8 secondes). Toute autre réponse (ou timeout) est considérée comme un échec de livraison de notre côté (voir Fiabilité).

09 · Webhooks

Événements

Format du payload reçu

{
  "event": "message.delivered",
  "messageId": "3EB09FB6BF40A3D9ABF1AD",
  "timestamp": "2026-07-10T14:32:00.000Z"
}

Chaque requête inclut un en-tête X-WP-Signature permettant de vérifier son authenticité (voir section suivante).

10 · Webhooks

Vérifier la signature

Chaque webhook est signé en HMAC-SHA256 avec le secret affiché dans votre espace développeur. Vérifiez systématiquement cette signature avant de traiter l'événement, pour vous assurer qu'il provient bien de nous et non d'un tiers malveillant.

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return expected === signatureHeader;
}

// Express — utilisez express.raw() sur cette route pour garder le corps brut
app.post('/webhooks/wp-api', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-wp-signature'];
  if (!isValidSignature(req.body, signature, process.env.WP_WEBHOOK_SECRET)) {
    return res.status(401).send('Signature invalide');
  }
  const payload = JSON.parse(req.body);
  console.log('Événement reçu :', payload.event);
  res.sendStatus(200);
});

11 · Webhooks

Confidentialité et statut « lu »

WhatsApp respecte un principe de confidentialité réciproque pour les confirmations de lecture : si un destinataire a désactivé « Confirmations de lecture » dans ses réglages WhatsApp, l'événement message.read ne sera jamais émis pour ses messages — quel que soit l'expéditeur, quelle que soit la plateforme utilisée pour envoyer.

12 · Webhooks

Fiabilité et nouvelles tentatives

À ce jour, chaque événement est relayé vers votre URL une seule fois, sans nouvelle tentative automatique en cas d'échec (timeout, erreur 5xx de votre côté, endpoint injoignable). L'échec est journalisé de notre côté mais n'est pas retenté.

En pratique : concevez votre endpoint pour répondre le plus vite possible (accusez réception immédiatement, puis traitez l'événement de façon asynchrone si le traitement est long), et gardez le statut de vos messages consultable via votre espace développeur comme source de vérité en complément des webhooks.

13

Besoin d'aide ?