WhatsApp pour les intégrateurs : gérer l'envoi de documents via l'API

L'envoi de documents via l'API WhatsApp Business est l'une des fonctionnalités les plus demandées par les éditeurs et intégrateurs qui cherchent à enrichir leurs plateformes. Factures, contrats, bons de livraison, notices produit : WhatsApp prend en charge une large gamme de formats et atteint vos destinataires là où ils lisent déjà leurs messages.

Ce que l'API permet d'envoyer comme documents

L'API WhatsApp Business Cloud de Meta distingue plusieurs types de médias. Pour les documents, voici ce que vous pouvez envoyer nativement :

Type de fichier	Extension	Taille max
PDF	.pdf	100 Mo
Word	.doc / .docx	100 Mo
Excel	.xls / .xlsx	100 Mo
PowerPoint	.ppt / .pptx	100 Mo
Texte brut	.txt	100 Mo

Chaque document peut être accompagné d'une caption (légende textuelle), ce qui permet d'ajouter du contexte sans message séparé. Le fichier est référencé soit par URL publique, soit par un media_id obtenu via l'endpoint d'upload de médias.

Structure minimale d'un appel API pour envoyer un document :

{
  "messaging_product": "whatsapp",
  "to": "33612345678",
  "type": "document",
  "document": {
    "link": "https://votre-cdn.com/facture-2026-001.pdf",
    "caption": "Votre facture du mois de juin",
    "filename": "facture-2026-001.pdf"
  }
}

Le champ filename contrôle le nom affiché à l'utilisateur final dans WhatsApp — pensez à le renseigner proprement plutôt que de laisser un nom de fichier technique.

Deux approches pour héberger les fichiers

Hébergement externe via URL publique

La méthode la plus simple : vous stockez le fichier sur votre CDN ou votre serveur, et vous passez l'URL directement dans l'appel. Meta télécharge le fichier au moment de l'envoi. Contrainte : l'URL doit être accessible depuis les serveurs Meta, sans authentification.

Upload préalable avec media_id

Pour des documents sensibles ou générés à la volée (factures personnalisées, contrats signés), utilisez l'endpoint d'upload :

POST https://graph.facebook.com/v20.0/{phone-number-id}/media

Vous obtenez un media_id valide 30 jours. C'est la meilleure approche pour des documents générés dynamiquement — vous uploadez d'abord, puis vous déclenchez l'envoi.

Consultez le guide complet de l'API WhatsApp Business pour les détails d'authentification et la gestion des tokens.

Intégrer l'envoi de documents dans votre plateforme

En tant qu'intégrateur, vous construisez probablement une abstraction au-dessus de l'API brute. Voici les points d'attention critiques :

Gestion des erreurs à prévoir :

• 131026 : lien média non accessible (URL protégée ou CORS)
• 131053 : format de fichier non supporté
• 100 : paramètre manquant ou malformé

Webhooks pour le suivi de livraison : Configurez votre endpoint webhook pour recevoir les événements messages.statuses :

• sent : le message est parti des serveurs Meta
• delivered : livré sur l'appareil du destinataire
• read : le destinataire a ouvert le message (et donc vu le document)

Pour la configuration des webhooks, référez-vous à l'article sur la configuration et réception des webhooks WhatsApp.

Templates vs messages de session : L'envoi de documents en dehors d'une fenêtre de 24h (conversation initiée par l'utilisateur) nécessite un template approuvé. Vous ne pouvez pas envoyer un document brut comme premier message sortant — il faut d'abord envoyer un template de type document contenant votre fichier en en-tête.

Cas d'usage les plus courants chez les intégrateurs :

• ERP / facturation : envoi automatique de factures PDF à chaque transaction
• Immobilier : transmission de compromis, diagnostics, états des lieux
• RH / formation : envoi de contrats de travail, supports de formation
• E-commerce : bons de livraison, certificats de garantie

Multi-tenant et gestion des numéros

Si vous construisez une plateforme multi-tenant — chaque client de votre SaaS envoie depuis son propre numéro WhatsApp —, vous devez gérer plusieurs phone-number-id distincts. L'API Whakup expose une architecture multi-numéros et multi-tenant nativement, ce qui vous évite de gérer vous-même la rotation des tokens et l'isolation des comptes.

La certification Meta Tech Provider de Whakup signifie aussi que vos clients finaux n'ont pas à passer par le processus de vérification Meta en autonomie — l'embedded signup intégré à votre plateforme prend en charge l'onboarding en quelques minutes.

Les tarifs Whakup sont transparents : 0,0088 €/message côté provider, auxquels s'ajoutent les frais Meta (0,0248 € pour les messages utility en France). Un document de facturation automatisé revient donc à environ 0,0336 €/envoi pour un message utility — largement inférieur à une impression et un envoi postal.

FAQ

Peut-on envoyer plusieurs documents dans un seul message WhatsApp ?

Non. L'API WhatsApp ne supporte qu'un seul média par message. Pour envoyer plusieurs documents, vous devez envoyer plusieurs messages successifs. Prévoyez un délai minimal entre chaque envoi pour éviter le rate limiting.

Les documents envoyés via l'API expirent-ils ?

Les media_id obtenus via l'endpoint d'upload expirent après 30 jours. Les documents déjà livrés dans la conversation restent accessibles à l'utilisateur tant qu'il ne les supprime pas. Pour les URL externes, tant que le fichier est accessible, les utilisateurs peuvent le re-télécharger depuis WhatsApp.

Faut-il un template approuvé pour envoyer un document ?

Oui, si vous initiez la conversation (message outbound hors fenêtre de 24h). Le template peut inclure un document en en-tête (header de type document). En revanche, dans une conversation active (fenêtre ouverte), vous pouvez envoyer un document libre sans template. Consultez le guide sur les catégories de templates WhatsApp pour choisir la bonne catégorie.

Quel format choisir entre URL externe et media_id pour des documents sensibles ?

Préférez le media_id pour tout document contenant des données personnelles (factures, contrats). Avec une URL externe, le fichier reste accessible tant que le lien est valide. Avec un media_id, vous contrôlez la durée de vie côté Meta et pouvez révoquer l'accès en supprimant le fichier source.

---

L'envoi de documents via l'API WhatsApp est une brique solide pour enrichir n'importe quelle plateforme métier. Si vous cherchez un accès API fiable, multi-tenant, hébergé en Europe et conforme RGPD, l'API WhatsApp Business de Whakup est conçue pour les intégrateurs qui construisent à grande échelle.