Intégration WhatsApp API PHP : guide pratique pour développeurs

PHP alimente encore aujourd'hui une part considérable des sites web et applications en Afrique francophone. Des plateformes e-commerce tournant sous WordPress/WooCommerce aux systèmes de gestion développés sur mesure pour des PME dakaroises ou abidjanaises, PHP reste un choix pragmatique pour des équipes avec des ressources limitées. Intégrer l'API WhatsApp Business Cloud dans un environnement PHP est tout à fait réalisable, sans framework complexe. Ce guide pratique vous montre exactement comment faire, avec des exemples de code directement réutilisables.

Prérequis et configuration

Avant de commencer, assurez-vous de disposer de PHP 7.4 ou supérieur avec l'extension cURL activée. Pour les projets modernes, PHP 8.1+ est recommandé. Vous aurez également besoin de vos identifiants Meta Developer : token d'accès, Phone Number ID et App Secret pour la vérification des webhooks.

Consultez le guide WhatsApp Business API pour obtenir ces identifiants si vous ne les avez pas encore.

Créez un fichier de configuration :

<?php
// config.php
define('WHATSAPP_TOKEN', getenv('WHATSAPP_TOKEN') ?: 'votre_token_ici');
define('PHONE_NUMBER_ID', getenv('PHONE_NUMBER_ID') ?: 'votre_phone_number_id');
define('VERIFY_TOKEN', getenv('VERIFY_TOKEN') ?: 'votre_verify_token');
define('APP_SECRET', getenv('APP_SECRET') ?: 'votre_app_secret');
define('API_URL', 'https://graph.facebook.com/v18.0/' . PHONE_NUMBER_ID . '/messages');

Envoyer des messages avec cURL

PHP propose deux approches principales pour interagir avec l'API WhatsApp : cURL natif et Guzzle (client HTTP). Voici une classe réutilisable qui encapsule les appels avec cURL :

<?php
// WhatsAppClient.php
require_once 'config.php';

class WhatsAppClient {
    
    private string $apiUrl;
    private string $token;
    
    public function __construct() {
        $this->apiUrl = API_URL;
        $this->token = WHATSAPP_TOKEN;
    }
    
    private function makeRequest(array $payload): array {
        $ch = curl_init($this->apiUrl);
        
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->token,
                'Content-Type: application/json'
            ],
            CURLOPT_TIMEOUT => 30,
            CURLOPT_SSL_VERIFYPEER => true
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        
        if (curl_errno($ch)) {
            throw new RuntimeException('cURL error: ' . curl_error($ch));
        }
        
        curl_close($ch);
        
        $data = json_decode($response, true);
        
        if ($httpCode >= 400) {
            throw new RuntimeException(
                'API error ' . $httpCode . ': ' . ($data['error']['message'] ?? 'Unknown error')
            );
        }
        
        return $data;
    }
    
    public function sendText(string $to, string $message): array {
        $payload = [
            'messaging_product' => 'whatsapp',
            'recipient_type' => 'individual',
            'to' => $to,
            'type' => 'text',
            'text' => ['body' => $message]
        ];
        
        return $this->makeRequest($payload);
    }
    
    public function sendTemplate(string $to, string $templateName, 
                                  string $lang = 'fr', array $params = []): array {
        $components = [];
        
        if (!empty($params)) {
            $components[] = [
                'type' => 'body',
                'parameters' => array_map(
                    fn($p) => ['type' => 'text', 'text' => $p], 
                    $params
                )
            ];
        }
        
        $payload = [
            'messaging_product' => 'whatsapp',
            'to' => $to,
            'type' => 'template',
            'template' => [
                'name' => $templateName,
                'language' => ['code' => $lang],
                'components' => $components
            ]
        ];
        
        return $this->makeRequest($payload);
    }
    
    public function sendImage(string $to, string $imageUrl, string $caption = ''): array {
        $payload = [
            'messaging_product' => 'whatsapp',
            'to' => $to,
            'type' => 'image',
            'image' => [
                'link' => $imageUrl,
                'caption' => $caption
            ]
        ];
        
        return $this->makeRequest($payload);
    }
}

// Utilisation
$wa = new WhatsAppClient();

// Envoyer un message texte à un client ivoirien
$result = $wa->sendText('225071234567', 'Votre commande #1234 est confirmée !');
echo 'Message ID : ' . $result['messages'][0]['id'];

// Envoyer un template avec variables
$wa->sendTemplate(
    '221771234567',
    'confirmation_paiement',
    'fr',
    ['Fatou Diallo', '12 500 FCFA', 'Orange Money']
);

Gérer les webhooks entrants en PHP

Un fichier PHP simple peut gérer les webhooks Meta sans framework. C'est une approche courante pour les projets PHP hébergés sur des hébergements mutualisés africains :

<?php
// webhook.php
require_once 'config.php';
require_once 'WhatsAppClient.php';

$method = $_SERVER['REQUEST_METHOD'];

// GET : vérification Meta lors de la configuration du webhook
if ($method === 'GET') {
    $mode = $_GET['hub_mode'] ?? '';
    $token = $_GET['hub_verify_token'] ?? '';
    $challenge = $_GET['hub_challenge'] ?? '';
    
    if ($mode === 'subscribe' && $token === VERIFY_TOKEN) {
        http_response_code(200);
        echo $challenge;
    } else {
        http_response_code(403);
        echo 'Forbidden';
    }
    exit;
}

// POST : réception des messages
if ($method === 'POST') {
    // Vérification de la signature Meta
    $signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
    $rawBody = file_get_contents('php://input');
    $expectedSig = 'sha256=' . hash_hmac('sha256', $rawBody, APP_SECRET);
    
    if (!hash_equals($signature, $expectedSig)) {
        http_response_code(401);
        echo 'Unauthorized';
        exit;
    }
    
    $data = json_decode($rawBody, true);
    
    if (isset($data['object']) && $data['object'] === 'whatsapp_business_account') {
        foreach ($data['entry'] ?? [] as $entry) {
            foreach ($entry['changes'] ?? [] as $change) {
                $messages = $change['value']['messages'] ?? [];
                foreach ($messages as $message) {
                    processMessage($message);
                }
            }
        }
    }
    
    http_response_code(200);
    echo json_encode(['status' => 'ok']);
    exit;
}

function processMessage(array $message): void {
    $wa = new WhatsAppClient();
    $from = $message['from'];
    $type = $message['type'];
    
    if ($type === 'text') {
        $text = strtolower(trim($message['text']['body']));
        
        switch (true) {
            case str_contains($text, 'commande'):
                $wa->sendText($from, "Pour commander, envoyez :\nNOM ARTICLE QUANTITÉ PRIX\nEx: Pagne 3 yards 2 15000");
                break;
            case str_contains($text, 'livraison'):
                $wa->sendText($from, "Délai de livraison : 24-48h à Dakar, 3-5 jours en région.");
                break;
            default:
                $wa->sendText($from, "Bonjour ! Comment puis-je vous aider ?\n• *commande* - Passer une commande\n• *livraison* - Infos livraison\n• *contact* - Parler à un conseiller");
        }
    }
    
    // Log dans la base de données
    logMessage($from, $type, $message);
}

function logMessage(string $from, string $type, array $message): void {
    // Connexion PDO à votre base MySQL
    // $pdo->prepare("INSERT INTO whatsapp_logs (from_number, type, payload, created_at) VALUES (?, ?, ?, NOW())")
    //     ->execute([$from, $type, json_encode($message)]);
}

Intégration avec WordPress et WooCommerce

Pour les nombreux e-commerces africains tournant sous WooCommerce, voici comment envoyer automatiquement une notification WhatsApp à la création d'une commande :

<?php
// Dans functions.php de votre thème ou dans un plugin custom

add_action('woocommerce_order_status_processing', 'send_whatsapp_order_confirmation', 10, 1);

function send_whatsapp_order_confirmation(int $orderId): void {
    $order = wc_get_order($orderId);
    if (!$order) return;
    
    // Récupérer le numéro depuis les métadonnées de commande ou profil client
    $phone = $order->get_billing_phone();
    if (empty($phone)) return;
    
    // Normaliser le numéro (exemple pour la Côte d'Ivoire)
    $phone = preg_replace('/[^0-9]/', '', $phone);
    if (substr($phone, 0, 3) !== '225') {
        $phone = '225' . ltrim($phone, '0');
    }
    
    require_once plugin_dir_path(__FILE__) . 'WhatsAppClient.php';
    $wa = new WhatsAppClient();
    
    $message = sprintf(
        "Bonjour %s ! 🎉\n\nVotre commande #%s de %s a été confirmée.\n\nNous vous contacterons pour la livraison sous 24-48h.\n\nMerci de votre confiance !",
        $order->get_billing_first_name(),
        $orderId,
        $order->get_formatted_order_total()
    );
    
    try {
        $wa->sendText($phone, $message);
    } catch (RuntimeException $e) {
        error_log('WhatsApp notification failed for order ' . $orderId . ': ' . $e->getMessage());
    }
}

Pour une solution clé en main sans développement personnalisé, Whakup offre des connecteurs natifs avec WooCommerce et d'autres plateformes e-commerce. Consultez également le guide sur l'utilisation de WhatsApp API sans développeur si vous préférez une approche no-code.

FAQ

Q: PHP est-il adapté pour des volumes importants de messages WhatsApp ?

R: PHP fonctionne bien pour des envois modérés (quelques milliers de messages par jour). Pour des volumes massifs, envisagez une architecture avec queue (Redis + worker PHP ou Laravel Queues) pour éviter les timeouts HTTP et respecter les rate limits de l'API WhatsApp. L'hébergement mutualisé a des limites de temps d'exécution qui peuvent poser problème pour les webhooks.

Q: Puis-je utiliser Guzzle au lieu de cURL natif pour appeler l'API WhatsApp ?

R: Oui, Guzzle est une excellente alternative à cURL natif. La syntaxe est plus lisible et il gère mieux les retries et les timeouts. Installez-le avec Composer : composer require guzzlehttp/guzzle. La structure des payloads JSON reste identique à ce guide.

Q: Comment stocker les tokens WhatsApp de façon sécurisée en PHP ?

R: Ne jamais mettre les tokens dans le code source ou dans des fichiers versionés (git). Utilisez des variables d'environnement via un fichier .env (avec vlucas/phpdotenv), les paramètres de configuration de votre hébergeur, ou un gestionnaire de secrets. Sur WordPress, les constantes dans wp-config.php (hors répertoire public) sont une option acceptable.

Q: Les webhooks WhatsApp fonctionnent-ils sur un hébergement mutualisé en France ou en Afrique ?

R: Oui, à condition que votre hébergeur supporte HTTPS (obligatoire par Meta) et que le serveur soit accessible depuis internet. Les hébergeurs comme OVH, Hostinger ou les fournisseurs cloud locaux (comme MTN Cloud ou Orange Business) fonctionnent bien. Vérifiez que le certificat SSL est valide et que les connexions entrantes sur le port 443 sont autorisées.

Q: Comment déboguer les webhooks WhatsApp en développement local avec PHP ?

R: Utilisez ngrok ou Cloudflare Tunnel pour exposer votre serveur local en HTTPS. Loggez le payload brut reçu dans un fichier (file_put_contents('webhook_log.txt', $rawBody . "\n", FILE_APPEND)) pour inspecter ce que Meta vous envoie. L'explorateur de webhooks dans le tableau de bord Meta Developer permet également d'envoyer des événements de test.

---

Votre intégration PHP est prête ? Connectez-la à Whakup pour gérer vos templates, vos campagnes et vos analytics directement depuis une interface intuitive, sans toucher à votre code métier.