WhatsApp pour l'envoi de documents via l'API : FAQ pour les éditeurs

L'API WhatsApp Business permet d'envoyer des fichiers (PDF, images, vidéos, documents Office) directement dans une conversation WhatsApp. Pour les éditeurs de plateformes qui intègrent ce canal, plusieurs questions techniques reviennent systématiquement. Cette FAQ regroupe les réponses les plus utiles.

Formats, tailles et types de médias

Quels types de médias peut-on envoyer via l'API ?

L'API WhatsApp distingue plusieurs catégories de médias :

Type	Formats acceptés	Taille max
document	PDF, DOCX, XLSX, PPTX, ZIP, CSV, TXT…	100 Mo
image	JPEG, PNG	5 Mo
video	MP4, 3GPP	16 Mo
audio	AAC, MP4, AMR, MPEG, OGG	16 Mo
sticker	WebP	500 Ko

Pour l'envoi de contrats, factures et devis, le type document avec un PDF est la solution standard.

Y a-t-il des formats bloqués ?

Meta bloque les fichiers .exe, .apk, .bat, .js et d'autres formats exécutables pour des raisons de sécurité. La liste complète est disponible dans la documentation officielle de l'API Cloud Meta.

Upload et hébergement des fichiers

Comment passer un fichier à l'API : URL ou upload direct ?

Deux méthodes coexistent :

• URL publique (link) : vous passez l'URL du fichier directement dans le payload. Meta télécharge le fichier au moment de l'envoi. L'URL doit être accessible sans authentification.
• Media ID : vous pré-uploadez le fichier via l'endpoint /media de l'API et obtenez un media_id. Utile pour envoyer le même fichier à de nombreux destinataires sans re-télécharger.

Pour la plupart des cas d'usage (factures individuelles, documents personnalisés), l'URL publique est plus simple. Pour les envois en masse d'un document identique, le media ID est plus efficace.

Combien de temps Meta conserve-t-il un média uploadé ?

Les médias uploadés via l'API sont conservés 30 jours. Après ce délai, le media_id devient invalide. Pour les documents récurrents (CGV, plaquette produit), il faut prévoir un mécanisme de re-upload.

Le fichier doit-il rester accessible après l'envoi ?

Non. Une fois que Meta a téléchargé le fichier (dans les secondes qui suivent l'appel API), l'URL peut devenir privée. Le fichier est alors stocké sur les serveurs Meta et distribué au destinataire depuis là.

Templates et fenêtre de conversation

Faut-il un template pour envoyer un document ?

Cela dépend du contexte :

• Dans la fenêtre de 24h (le contact vous a écrit dans les dernières 24h) : vous pouvez envoyer n'importe quel type de message libre, y compris un document.
• Hors fenêtre de 24h : obligatoirement un template HSM approuvé par Meta. Le template peut inclure un en-tête de type document (pour joindre un fichier au message).

La catégorie du template (utility, marketing, authentication) détermine le coût Meta applicable. Un envoi de facture relève généralement de utility. Voir le détail des catégories de templates WhatsApp.

Peut-on personnaliser le nom du fichier affiché dans WhatsApp ?

Oui, via le paramètre filename dans le payload. C'est recommandé pour que l'utilisateur identifie immédiatement le fichier. Un nom générique comme document.pdf crée de la confusion. Préférez Facture-2026-0451-Dupont.pdf.

Webhooks et tracking

Comment suivre la livraison et la lecture d'un document ?

Les webhooks de statut fonctionnent exactement comme pour les messages texte :

• sent : message transmis aux serveurs Meta
• delivered : message délivré sur l'appareil du destinataire
• read : message ouvert dans WhatsApp

Ces statuts sont envoyés vers votre endpoint webhook configuré dans le tableau de bord Meta. Il n'existe pas de webhook spécifique indiquant que le fichier a été téléchargé ou ouvert en dehors de WhatsApp.

Que faire si le webhook delivered n'arrive jamais ?

Plusieurs causes possibles : le numéro n'est pas sur WhatsApp, le téléphone est hors ligne, ou le destinataire a bloqué votre numéro. Dans tous les cas, Meta renvoie une erreur ou un statut failed avec un code d'erreur précis. Votre plateforme doit traiter ces erreurs pour déclencher un fallback (email, SMS).

Spécificités multi-tenant

Dans une architecture multi-tenant, comment gérer les médias de chaque client ?

Les media IDs sont liés à un numéro WhatsApp Business spécifique (WABA). Un fichier uploadé depuis le compte du client A ne peut pas être réutilisé depuis le compte du client B. Votre plateforme doit donc gérer l'upload par compte, pas de manière centralisée.

C'est l'un des points structurants à prévoir dans une intégration API WhatsApp Business multi-tenant. Whakup gère nativement le multi-numéros et le multi-tenant — chaque compte client est isolé, avec ses propres credentials et son propre espace média.

Peut-on envoyer le même document à 10 000 contacts en une seule campagne ?

Techniquement oui, mais les limites de tiers de messagerie s'appliquent (nombre de conversations initiées par l'entreprise par période de 24h). Un compte qui démarre est limité à 1 000 conversations business-initiated par jour. Cette limite monte automatiquement selon la qualité du compte. Consulter le guide complet de l'API WhatsApp Business pour comprendre la progression des tiers.

FAQ complémentaire

Peut-on envoyer plusieurs documents dans un seul message ?

Non. L'API WhatsApp ne supporte qu'un seul média par message. Si vous devez envoyer plusieurs fichiers, envoyez plusieurs messages successifs. Pour les templates, un seul en-tête de type document est autorisé par template.

Est-ce que WhatsApp compresse les documents comme il le fait pour les images ?

Non. Les documents (type document) sont transmis sans compression. Les images envoyées en type image subissent une compression. Si vous avez besoin d'envoyer une image en qualité originale (un scan, par exemple), envoyez-la comme document avec l'extension .jpg ou .png.

L'envoi de documents fonctionne-t-il avec WhatsApp Business App ou uniquement avec l'API ?

Cette FAQ concerne uniquement l'API WhatsApp Business. L'application WhatsApp Business (version mobile) permet aussi d'envoyer des documents manuellement, mais sans automatisation ni intégration à une plateforme SaaS.

Whakup gère-t-il la soumission des templates pour l'envoi de documents ?

Oui. En tant que Meta Tech Provider certifié, Whakup soumet et suit les templates HSM au nom de ses partenaires éditeurs. Vous n'avez pas besoin d'accéder directement au Meta Business Manager pour la gestion des templates.

---

Pour intégrer l'envoi de documents WhatsApp dans votre plateforme, l'API WhatsApp de Whakup offre une intégration REST directe, un embedded signup pour onboarder vos clients sans friction, et une infrastructure hébergée en Europe. Tarif Whakup : 0,0088 €/msg hors frais Meta, avec support technique dédié aux éditeurs.