Aller au contenu principal
A - Configuration & Setup• 6 min de lecture

Whakup API documentation : guide integration pour developpeurs

Guide complet d'intégration de l'API Whakup pour développeurs : authentification, endpoints principaux, webhooks, exemples de code et bonnes pratiques d'implémentation.

L'API Whakup permet aux développeurs d'intégrer les capacités WhatsApp Business directement dans leurs applications, CRM personnalisés ou workflows sur mesure. Ce guide couvre l'essentiel pour démarrer une intégration propre et robuste.

Architecture de l'API Whakup

L'API Whakup est une API REST standard. Elle expose des endpoints HTTP qui retournent des réponses JSON. Elle s'appuie sur l'API WhatsApp Business de Meta — Whakup agit comme couche d'abstraction qui simplifie l'accès, gère les tokens Meta, les quotas et les complexités d'infrastructure.

Ce que l'API Whakup vous permet de faire :

  • Envoyer des messages (texte, médias, templates HSM, messages interactifs)
  • Recevoir des messages et événements via webhooks
  • Gérer les contacts (créer, modifier, segmenter)
  • Déclencher des workflows d'automation
  • Accéder aux données analytics
  • Gérer les templates de messages

Ce que l'API Whakup gère pour vous :

  • Authentification et refresh des tokens Meta
  • Gestion des limites de taux (rate limiting)
  • Retry automatique en cas d'erreur transitoire
  • Normalisation des numéros de téléphone
  • Gestion des statuts de livraison

La différence avec une intégration directe à l'API WhatsApp Business est significative : l'infrastructure technique WhatsApp API montre à quel point la gestion de la couche Meta est complexe sans une couche d'abstraction.

Authentification

L'API Whakup utilise des API Keys pour l'authentification. Elles se génèrent depuis votre dashboard Whakup sous Paramètres > API.

Header requis pour chaque requête :

Authorization: Bearer {votre_api_key}
Content-Type: application/json

Bonnes pratiques pour les API Keys :

  • Ne jamais stocker les API Keys dans le code source (utilisez des variables d'environnement)
  • Créer des clés distinctes par environnement (développement, staging, production)
  • Limiter les permissions de chaque clé au minimum nécessaire
  • Régénérer les clés en cas de compromission suspectée
  • Stocker les clés dans un gestionnaire de secrets (Vault, AWS Secrets Manager, etc.)

Endpoints principaux

Envoyer un message texte :

POST /api/v1/messages/send
{
  "to": "+221701234567",
  "type": "text",
  "text": {
    "body": "Bonjour, votre commande est confirmée."
  }
}

Envoyer un template HSM :

POST /api/v1/messages/send
{
  "to": "+225071234567",
  "type": "template",
  "template": {
    "name": "confirmation_commande",
    "language": "fr",
    "components": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "Marie Koné"},
          {"type": "text", "text": "#CMD-2024-789"},
          {"type": "text", "text": "2-3 jours ouvrés"}
        ]
      }
    ]
  }
}

Envoyer un message avec boutons interactifs :

POST /api/v1/messages/send
{
  "to": "+237681234567",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {"text": "Voulez-vous confirmer votre rendez-vous ?"},
    "action": {
      "buttons": [
        {"type": "reply", "reply": {"id": "confirm_yes", "title": "Confirmer"}},
        {"type": "reply", "reply": {"id": "confirm_no", "title": "Annuler"}}
      ]
    }
  }
}

Récupérer l'historique d'un contact :

GET /api/v1/contacts/{phone_number}/messages?limit=50&offset=0

Créer ou mettre à jour un contact :

POST /api/v1/contacts
{
  "phone": "+221701234567",
  "name": "Aminata Diallo",
  "email": "aminata@example.com",
  "custom_fields": {
    "ville": "Dakar",
    "segment": "VIP",
    "date_inscription": "2024-01-15"
  },
  "tags": ["client", "vip", "dakar"]
}

Configuration des webhooks

Les webhooks permettent à Whakup de notifier votre système en temps réel lors d'événements : message reçu, statut de livraison, opt-out d'un contact, etc.

Configuration dans le dashboard :

  1. Aller dans Paramètres > Webhooks
  2. Ajouter l'URL de votre endpoint
  3. Sélectionner les événements à recevoir
  4. Configurer le secret de validation (HMAC-SHA256)

Format d'un événement webhook (message reçu) :

{
  "event": "message.received",
  "timestamp": "2024-11-15T14:32:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "+221701234567",
    "contact_name": "Aminata Diallo",
    "type": "text",
    "text": "Bonjour, je voudrais savoir si...",
    "timestamp": "2024-11-15T14:31:55Z"
  }
}

Validation du webhook (Python) :

import hmac
import hashlib

def validate_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Types d'événements disponibles :

  • message.received — Nouveau message entrant
  • message.delivered — Message livré au destinataire
  • message.read — Message lu par le destinataire
  • contact.opted_out — Contact a opt-outé
  • contact.created — Nouveau contact créé
  • flow.completed — Workflow automation terminé

Gestion des erreurs

L'API Whakup retourne des codes HTTP standards :

Code Signification
200 Succès
400 Requête malformée (vérifier le payload)
401 API Key invalide ou expirée
403 Permission insuffisante
404 Ressource non trouvée
429 Rate limit dépassé (attendre avant de retry)
500 Erreur serveur (retry avec backoff exponentiel)

Exemple de réponse d'erreur :

{
  "error": {
    "code": "TEMPLATE_NOT_APPROVED",
    "message": "Le template 'confirmation_commande' n'est pas encore approuvé par Meta.",
    "details": {
      "template_name": "confirmation_commande",
      "status": "PENDING"
    }
  }
}

Stratégie de retry recommandée : Pour les erreurs 429 et 5xx, implémentez un backoff exponentiel : attendre 1s, puis 2s, puis 4s, jusqu'à 5 tentatives maximum. Pour les erreurs 4xx (sauf 429), ne pas retry — l'erreur est dans la requête.

Rate limits et quotas

L'API Whakup impose des limites de taux qui correspondent aux limites Meta :

  • Messages sortants : Selon le tier de votre numéro (1 000 / 10 000 / 100 000 conversations par jour)
  • Appels API : Généralement 1 000 requêtes par minute par API Key
  • Webhooks : Votre endpoint doit répondre dans les 5 secondes (sinon Whakup considère l'échec et retente)

Pour les envois de masse (broadcasts), utilisez l'endpoint dédié /api/v1/campaigns/send qui gère automatiquement le rate limiting et la planification des envois.

Exemples d'intégrations courantes

Intégration e-commerce (Node.js) :

// Déclencher un message de confirmation de commande
async function sendOrderConfirmation(order) {
  const response = await fetch('https://api.whakup.com/v1/messages/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WHAKUP_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: order.customerPhone,
      type: 'template',
      template: {
        name: 'order_confirmation',
        language: 'fr',
        components: [{
          type: 'body',
          parameters: [
            { type: 'text', text: order.customerName },
            { type: 'text', text: order.orderId },
            { type: 'text', text: order.estimatedDelivery }
          ]
        }]
      }
    })
  });
  return response.json();
}

FAQ

L'API Whakup est-elle disponible dans tous les plans ? Non. L'API REST, les webhooks et le MCP sont réservés à l'offre Business (450 € HT/mois), et les envois API sont facturés au message. Les offres Gratuite, Basique et Essentiel n'incluent pas d'accès API.

Comment tester l'API sans impacter les vrais clients ? Utilisez le mode sandbox Whakup (disponible dans les paramètres développeur). En mode sandbox, les messages ne sont pas envoyés réellement — ils sont loggés pour inspection. Idéal pour développer et tester sans coûts Meta.

L'API supporte-t-elle les messages en langues africaines (wolof, bambara, etc.) ? Oui. L'API transmet le contenu textuel tel quel — si vous envoyez du texte en wolof ou en bambara, il sera reçu en wolof ou bambara. Les templates nécessitent une approbation Meta avec la langue indiquée. Meta supporte de nombreuses langues africaines dans ses templates.

Comment gérer les numéros de téléphone au format local africain ? Whakup normalise automatiquement les numéros si vous envoyez le format E.164 international (+221XXXXXXXXX pour le Sénégal). Pour les numéros locaux sans indicatif pays, configurez le pays par défaut dans les paramètres de votre compte Whakup.


L'API Whakup offre une interface propre et bien documentée qui simplifie considérablement l'intégration WhatsApp Business dans vos applications. La couche d'abstraction Whakup vous évite de gérer la complexité de l'API Meta directement.

Accédez à la documentation complète et à vos clés API. Créez votre compte Whakup et démarrez votre intégration dès aujourd'hui.

#whatsapp marketing#whakup api#integration whakup developpeurs
Pablo Lenormand
Pablo LenormandCo-fondateur & CPO

Co-fondateur et Chief Product Officer de Whakup, Pablo conçoit les fonctionnalités qui permettent aux marques africaines de maximiser leur impact sur WhatsApp.

🚀

Prêt à passer à l'action ?

Essayez Whakup gratuitement pendant 15 jours. Aucune carte bancaire requise.

Démarrer l'essai gratuit