WhatsApp pour les agences push notifications : gérer l'envoi de documents via l'API

L'envoi de documents via WhatsApp via l'API Business répond à un besoin très concret pour les plateformes push notifications : délivrer des fichiers directement dans la messagerie que l'utilisateur consulte plusieurs fois par jour. Contrats, factures, bulletins de paie, rapports, bons de commande — tous ces documents arrivent dans un canal à fort taux d'ouverture, sans pièce jointe email perdue dans les spams. Pour les agences qui construisent des solutions métier sur la notification, c'est une extension naturelle de l'offre.

Formats et limites techniques pour l'envoi de documents WhatsApp

L'API WhatsApp Business supporte plusieurs types de fichiers en pièce jointe. Voici ce que vous pouvez envoyer et les contraintes à respecter dans votre intégration.

Formats supportés :

Type de fichier	Extensions	Taille max
Documents	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT	100 Mo
Images	JPEG, PNG, WEBP	5 Mo
Vidéo	MP4, 3GP	16 Mo
Audio	AAC, MP4, AMR, OGG	16 Mo

Pour l'envoi de documents professionnels, le PDF reste le format le plus fiable. Il est lisible sur tous les appareils sans problème de mise en page et Meta l'affiche avec une prévisualisation du nom de fichier.

Limites à anticiper dans votre plateforme :

• Le fichier doit être accessible via une URL HTTPS publique ou préalablement uploadé via l'API Media de Meta.
• Les URL signées (S3, GCS) avec expiration courte fonctionnent, mais l'URL doit être valide au moment de l'envoi.
• Le nom du fichier visible dans WhatsApp correspond au nom du fichier dans l'URL ou à celui spécifié dans le paramètre filename de l'API.
• Les documents ne peuvent pas être envoyés dans un template HSM seul : ils s'envoient soit dans une session active (message entrant récent), soit dans un template de type media (header de type document).

Pour comprendre la structure des templates avec header media, consultez notre article sur les catégories et types de templates WhatsApp.

Deux modes d'envoi : session et template

La distinction session / template est centrale pour l'envoi de documents dans une plateforme push.

Envoi en session (dans les 24h après un message entrant) : Vous pouvez envoyer n'importe quel document supporté sans passer par un template préapprouvé. Ce mode est idéal pour les usages réactifs : un conseiller répond à une demande et joint directement un contrat en PDF. C'est le mode le plus flexible, mais il exige qu'un message entrant ait ouvert la fenêtre de session.

Envoi via template avec header document : Pour les envois proactifs (hors session), vous devez utiliser un template approuvé par Meta avec un header de type DOCUMENT. Ce template peut contenir des variables dans le corps du message (numéro de facture, date, montant) mais le document lui-même est passé dynamiquement au moment de l'appel API — il n'est pas fixé dans le template.

Exemple de structure d'appel API pour un envoi de facture via template :

{
  "type": "template",
  "template": {
    "name": "envoi_facture_client",
    "language": { "code": "fr" },
    "components": [
      {
        "type": "header",
        "parameters": [{
          "type": "document",
          "document": {
            "link": "https://votre-cdn.com/factures/INV-2026-0042.pdf",
            "filename": "Facture-INV-2026-0042.pdf"
          }
        }]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "INV-2026-0042" },
          { "type": "text", "text": "42,00 €" }
        ]
      }
    ]
  }
}

Ce template doit être soumis à Meta avec un exemple de document PDF. Le délai d'approbation est généralement de quelques heures à 24h.

Intégration dans une plateforme push notifications

Pour une agence qui gère plusieurs clients via une architecture multi-tenant, l'envoi de documents WhatsApp soulève des questions d'orchestration spécifiques.

Gestion du stockage des documents. Les fichiers doivent être accessibles via URL publique HTTPS au moment de l'envoi. Si vos clients stockent leurs documents dans des environnements privés (S3 avec ACL privé, SFTP), votre plateforme doit générer des URL temporaires signées avant chaque envoi. Gérez l'expiration de ces URLs avec une marge suffisante.

Pipeline de renommage. Le nom du fichier visible par l'utilisateur final est critique pour l'expérience. Un fichier nommé export_12345_v2_final.pdf génère de la confusion. Votre plateforme doit permettre au client de définir un pattern de nommage (Facture-{{num_facture}}-{{date}}.pdf) appliqué dynamiquement.

Traçabilité des envois. Pour les documents à valeur légale (contrats, bulletins de salaire, avis de passage), conservez le statut de délivrance WhatsApp (delivered, read) associé au document envoyé. Ces statuts sont reçus via webhook. Whakup expose ces événements en temps réel vers votre endpoint.

Quotas et tiers de messagerie. L'envoi d'un document compte comme un message dans les quotas Meta. Si votre client envoie 50 000 bulletins de paie le même jour, assurez-vous que le numéro source est en tier 3 (100 000 messages/24h). La montée en tier est progressive — anticipez-la en testant et en réchauffant les numéros en amont.

Pour l'architecture multi-numéros et la gestion des tiers, notre article sur les meilleurs BSP WhatsApp en France compare les options disponibles.

Cas d'usage prioritaires pour les agences push

Voici les cas d'usage où l'envoi de documents WhatsApp crée le plus de valeur par rapport aux canaux traditionnels :

• Bulletins de salaire : distribution aux employés sans adresse email professionnelle ou avec des boîtes surchargées. WhatsApp garantit un accès immédiat depuis le mobile.
• Contrats et devis : envoi direct après un rendez-vous commercial, avec accusé de lecture pour relancer au bon moment.
• Factures et avoirs : délivrance automatique post-transaction, dans le même fil que les notifications de commande.
• Rapports clients : envoi mensuel de rapports de performance ou de récapitulatifs dans les secteurs conseil, immobilier, finance.
• Documents administratifs : convocations, attestations, formulaires pré-remplis pour les services RH ou les organismes publics.

Dans tous ces cas, l'API Whakup permet de configurer les envois sans que chaque client de votre agence ait à gérer sa propre intégration Meta. Voir l'API WhatsApp Business Whakup pour les détails d'implémentation.

FAQ

Peut-on envoyer plusieurs documents dans le même message WhatsApp ?

Non. Un message WhatsApp ne peut contenir qu'un seul fichier. Pour envoyer plusieurs documents, envoyez plusieurs messages successifs. Meta ne facture pas d'unité supplémentaire pour plusieurs messages dans la même session, mais chaque message template compte séparément hors session.

Les documents envoyés via WhatsApp restent-ils téléchargeables longtemps ?

WhatsApp conserve les médias pendant 30 jours côté serveur Meta. Après ce délai, le fichier n'est plus accessible depuis l'application si l'utilisateur ne l'a pas téléchargé localement. Pour les documents à conserver, informez l'utilisateur de télécharger le fichier.

Faut-il uploader le document chez Meta ou peut-on utiliser une URL directe ?

Les deux options fonctionnent. Pour les templates, une URL HTTPS directe est suffisante. Meta télécharge le fichier au moment de l'envoi. Pour des envois répétés du même document (ex : CGV standard), l'upload préalable via l'API Media donne un media_id réutilisable et évite de dépendre de la disponibilité de l'URL source.

WhatsApp envoie-t-il une notification de lecture pour les documents ?

Oui, si l'utilisateur a activé les accusés de lecture dans WhatsApp (paramètre par défaut activé). Vous recevez un webhook avec le statut read dès que l'utilisateur ouvre le message. Cela ne garantit pas qu'il a ouvert le document lui-même, seulement qu'il a vu le message.

---

Whakup est un Meta Tech Provider certifié qui fournit l'API WhatsApp Business en marque blanche aux agences et éditeurs de plateformes. Pour intégrer l'envoi de documents dans votre solution push notifications, découvrez l'API Whakup — sandbox disponible sans engagement, hébergement EU, conformité RGPD.