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

Envoyer un document PDF via l'API WhatsApp Business demande trois étapes : uploader le fichier, construire le payload, envoyer le message. Ce tutoriel vous guide de A à Z avec des exemples de code concrets, pour un développeur qui intègre cette fonctionnalité dans une plateforme SaaS.

Étape 1 — Uploader le document via l'API Media

Avant d'envoyer un document à un utilisateur, vous devez uploader le fichier sur les serveurs Meta via l'API Media. Cette étape retourne un media_id réutilisable pendant 30 jours.

curl -X POST \
  "https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/media" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/chemin/vers/facture-2026-001.pdf;type=application/pdf" \
  -F "messaging_product=whatsapp"

Réponse attendue :

{
  "id": "1234567890123456"
}

Stockez ce media_id dans votre base de données ou cache. Vous pouvez l'utiliser pour envoyer le même document à plusieurs destinataires sans re-uploader.

Si votre fichier est déjà accessible via une URL HTTPS publique (S3, GCS, Azure Blob), vous pouvez passer l'URL directement dans le payload sans passer par l'upload — voir l'étape 2.

Étape 2 — Envoyer le document en message libre (fenêtre 24h)

Si votre utilisateur vous a envoyé un message dans les dernières 24 heures, vous pouvez envoyer un document libre (sans template). C'est le cas typique d'un agent support qui partage un fichier en réponse à une demande.

Avec un media_id :

curl -X POST \
  "https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "+33612345678",
    "type": "document",
    "document": {
      "id": "1234567890123456",
      "filename": "Facture-2026-001.pdf",
      "caption": "Voici votre facture de janvier 2026. Pour toute question, répondez à ce message."
    }
  }'

Avec une URL directe :

curl -X POST \
  "https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "+33612345678",
    "type": "document",
    "document": {
      "link": "https://votre-cdn.exemple.com/documents/facture-2026-001.pdf",
      "filename": "Facture-2026-001.pdf",
      "caption": "Voici votre facture de janvier 2026."
    }
  }'

L'URL doit être accessible publiquement. Les URLs avec authentification par header ne fonctionnent pas — utilisez des signed URLs avec expiration.

Étape 3 — Envoyer le document via un template (envoi proactif)

Pour les envois initiés par votre plateforme (facture mensuelle automatique, devis envoyé sans interaction préalable), vous devez passer par un template approuvé avec un document en composant header.

Créer le template

curl -X POST \
  "https://graph.facebook.com/v19.0/{WABA_ID}/message_templates" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "envoi_facture_mensuelle",
    "language": "fr",
    "category": "UTILITY",
    "components": [
      {
        "type": "HEADER",
        "format": "DOCUMENT"
      },
      {
        "type": "BODY",
        "text": "Bonjour {{1}},\n\nVotre facture {{2}} est disponible ci-dessus.\n\nMontant TTC : {{3}} €\nDate d'échéance : {{4}}\n\nMerci pour votre confiance."
      },
      {
        "type": "FOOTER",
        "text": "Pour toute question, répondez à ce message."
      }
    ]
  }'

Attendez l'approbation Meta (généralement moins de 24 heures). Pour comprendre les règles qui régissent les templates de catégorie UTILITY, consultez l'article sur les catégories de templates WhatsApp.

Envoyer le template avec le document

curl -X POST \
  "https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "+33612345678",
    "type": "template",
    "template": {
      "name": "envoi_facture_mensuelle",
      "language": { "code": "fr" },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "id": "1234567890123456",
                "filename": "Facture-2026-001.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Marie Dupont" },
            { "type": "text", "text": "FAC-2026-001" },
            { "type": "text", "text": "1 250,00" },
            { "type": "text", "text": "31 janvier 2026" }
          ]
        }
      ]
    }
  }'

Étape 4 — Vérifier les statuts de livraison

Configurez votre webhook pour recevoir les statuts d'envoi. Voici un exemple Node.js :

app.post('/webhook/whatsapp', express.json(), (req, res) => {
  const entry = req.body?.entry?.[0];
  const changes = entry?.changes?.[0]?.value;

  // Statuts de livraison
  if (changes?.statuses) {
    changes.statuses.forEach(status => {
      console.log(`Message ${status.id}: ${status.status}`);

      if (status.status === 'delivered') {
        // Marquer le document comme livré dans votre base
        markDocumentDelivered(status.id);
      }

      if (status.status === 'failed') {
        // Alerter et envisager un fallback (email)
        handleDeliveryFailure(status.id, status.errors);
      }
    });
  }

  res.sendStatus(200);
});

Les statuts possibles sont sent (transmis à WhatsApp), delivered (reçu sur l'appareil), read (ouvert par l'utilisateur) et failed (échec avec code d'erreur).

Pour la configuration détaillée des webhooks, l'article webhooks WhatsApp API : configuration et réception couvre tous les événements disponibles.

Récapitulatif des étapes

Étape	Action	Endpoint
1	Upload du PDF	POST /{phone-id}/media
2	Envoi message libre	POST /{phone-id}/messages (type: document)
3	Création template	POST /{waba-id}/message_templates
4	Envoi via template	POST /{phone-id}/messages (type: template)
5	Réception statuts	Webhook POST sur votre endpoint

FAQ

Comment nommer le fichier affiché dans WhatsApp ?

Le champ filename dans le payload contrôle le nom affiché. Utilisez un nom descriptif avec l'extension : Facture-FAC-2026-001.pdf est meilleur que document.pdf. Le nom de fichier ne peut pas contenir de caractères spéciaux (/ \ : * ? " < > |).

Peut-on envoyer un document sans caption ?

Oui, le champ caption est optionnel. Sans caption, seul le fichier apparaît dans la conversation. Avec caption, un texte accompagne le document. La caption est limitée à 1 024 caractères.

Le template avec document en header peut-il aussi avoir des boutons ?

Oui. Vous pouvez ajouter un composant BUTTONS à votre template avec des boutons de type QUICK_REPLY (ex: "Confirmer la réception") ou CALL_TO_ACTION (ex: lien vers votre portail client). Les boutons sont définis lors de la création du template et ne peuvent pas être modifiés sans créer un nouveau template.

Quel est le coût d'envoi d'un document par WhatsApp ?

Le coût est identique à tout autre message template : 0,0336 €/message pour un template UTILITY depuis un numéro français (0,0248 € Meta + 0,0088 € Whakup). Il n'y a pas de surcoût pour les pièces jointes. La taille du fichier n'impacte pas le prix. Plus de détails dans l'article sur les prix de l'API WhatsApp Business en 2026.

---

Prêt à intégrer l'envoi de documents dans votre plateforme ? Accédez à l'API WhatsApp Business Whakup pour un accès sandbox immédiat : testez l'upload de médias et l'envoi de votre premier PDF en quelques minutes, sans configuration Meta de votre côté.