API WhatsApp : formats de fichiers et limites de taille

Faut-il téléverser le média ou envoyer un lien ?

Meta recommande de téléverser le fichier et d'envoyer son ID de média. Vous pouvez aussi envoyer un lien vers un fichier hébergé sur un serveur public, mais les références de Meta pour les images, les vidéos et les documents préconisent l'ID téléversé pour de meilleures performances, et ses conseils sur le débit disent la même chose pour les gros volumes.

Avec le point de terminaison de Meta, un téléversement est un POST vers /<PHONE_NUMBER_ID>/media avec le fichier, son type MIME et messaging_product=whatsapp, et la réponse est {"id": "<MEDIA_ID>"}. Les fichiers téléversés sont chiffrés et conservés 30 jours, sauf si vous les supprimez avant.

Sur le point de terminaison WhatsApp d'OmniChannels.ai, un message média prend soit mediaUrl (une URL HTTPS publique), soit mediaFile (un fichier que vous téléversez avec la requête), avec la légende dans content. Consultez la documentation de l'API WhatsApp. Demandez à notre équipe comment votre compte gère le stockage et la réutilisation des médias pour les envois volumineux.

Combien de temps les ID de média restent-ils valables ?

Meta indique 30 jours pour un ID renvoyé par un téléversement et 7 jours pour un ID reçu dans un webhook entrant. L'URL de téléchargement renvoyée pour un ID expire au bout de 5 minutes.

Conséquences pratiques :

• Ne conservez pas un ID de média en cache pendant des mois. Gardez votre fichier d'origine et téléversez-le à nouveau lorsqu'un ID est rejeté.
• Téléchargez les fichiers entrants dès que l'événement arrive et gardez votre propre copie.
• Ne stockez jamais une URL de téléchargement récupérée ; demandez-en une nouvelle quand vous en avez besoin.

Peut-on ajouter des légendes aux messages média ?

Oui. Les messages image, vidéo et document acceptent une légende facultative de 1 024 caractères maximum, d'après les références de messages de Meta. Les légendes sont du texte brut placé à côté du fichier.

Les messages audio et sticker n'ont pas de légende dans ce modèle. Si vous voulez accompagner un message vocal de quelques mots, envoyez un court message texte à côté. Dans la fenêtre de service client, les légendes sont libres ; en dehors, le média doit passer dans un modèle approuvé.

Comment les médias fonctionnent-ils dans les modèles de message ?

Un modèle peut comporter une image, une vidéo ou un document dans son en-tête, et cet en-tête est figé à la création du modèle. Lorsque vous soumettez un modèle à approbation, vous fournissez un fichier d'exemple, et vous pouvez fournir le fichier réel au moment de l'envoi.

Sur notre API, headerFormat peut valoir IMAGE, VIDEO ou DOCUMENT à la création, headerFile transporte l'exemple, et mediaUrl à l'envoi remplace le média de l'en-tête. Consultez la documentation des modèles de Meta pour les exigences sur les fichiers d'exemple. Voir catégories de modèles et approbation et exemples de modèles.

Comment télécharger un média envoyé par un client ?

Un média entrant arrive par un webhook avec un ID de média ; vous le convertissez en URL et le téléchargez avec une autorisation.

1. Lisez l'ID de média dans l'événement du message entrant.
2. Demandez l'URL du média pour cet ID. La réponse de Meta inclut url, mime_type, sha256 et file_size.
3. Envoyez un GET à cette URL avec un en-tête Authorization: Bearer <token>. Sans le jeton, la requête échoue.
4. Vérifiez l'en-tête Content-Type et la valeur sha256, puis stockez le fichier.
5. En cas de 404, demandez une nouvelle URL et réessayez ; si cela échoue encore, renouvelez le jeton d'accès.

La taille maximale des médias entrants sur l'API Cloud est de 100 Mo chez Meta. Un fichier plus gros déclenche un webhook avec le code d'erreur 131052 ; demandez au client d'envoyer un fichier plus léger ou de le partager autrement. Analysez chaque fichier avant de l'ouvrir en interne. Voir le guide des webhooks, et confirmez avec votre ingénieur d'onboarding comment les médias entrants sont remis sur votre compte.

Exemple concret : une clinique dentaire qui envoie des comptes rendus

« Nile Smile Clinic » (synthétique), au Caire, envoie des cartes de rendez-vous et des comptes rendus de radiographie.

1. Les cartes de rendez-vous sont des images PNG de 300 Ko avec une légende de deux lignes. Bien en dessous de 5 Mo.
2. Les comptes rendus de traitement sont des PDF de 2 à 8 Mo, nommés report-2026-0381.pdf, envoyés comme documents.
3. Une vidéo de visite de la clinique de 25 Mo est trop lourde pour une vidéo. L'équipe la réencode en MP4 H.264/AAC de moins de 16 Mo avec faststart.
4. Les patients envoient des photos d'ordonnances. La boîte de réception télécharge chaque fichier immédiatement, car l'ID entrant expire après 7 jours.
5. Un message d'accueil vocal est exporté en OGG Opus mono, car les autres variantes d'OGG sont rejetées.

Quelles sont les erreurs courantes ?

• Juger uniquement sur la taille. Une image de 3 Mo dans le mauvais format colorimétrique ou une vidéo avec le mauvais codec échoue quand même.
• Incohérence de type MIME. Un .jpg servi en application/octet-stream est une cause classique de l'erreur 131053.
• Un lien vers une URL lente ou privée, comme un lien signé expiré ou une page protégée par une connexion.
• S'appuyer sur un ancien ID de média. Les ID expirent après 30 jours.
• Ignorer l'expiration des ID entrants. Les fichiers des clients doivent être enregistrés dans les 7 jours.
• Un WebP animé comme image. Il est rejeté ; utilisez un sticker ou une vidéo.
• Les limites changent. Revérifiez la référence de Meta avant de figer vos règles de validation.

Comment OmniChannels.ai vous aide

OmniChannels.ai envoie des messages WhatsApp image, vidéo, audio, document et sticker via une seule API, avec un lien public ou un fichier téléversé et une légende, et affiche les médias et les pièces jointes dans la boîte de réception partagée. BroadNet est un Business Solution Provider officiel de Meta : les modèles avec en-tête image, vidéo ou document peuvent donc être créés et suivis avec leur statut d'approbation. Lisez la documentation de l'API WhatsApp et les erreurs et limites, ou découvrez le canal WhatsApp.