Media nell'API WhatsApp: tipi di file e limiti di dimensione

Conviene caricare il media o inviare un link?

Meta consiglia di caricare il file e inviare il suo ID media. In alternativa potete inviare un link a un file su un server pubblico, ma i riferimenti di Meta per immagini, video e documenti indicano di preferire l'ID caricato per prestazioni migliori, e le sue indicazioni sul throughput dicono lo stesso per i volumi più alti.

Con l'endpoint di Meta, un upload è una POST a /<PHONE_NUMBER_ID>/media con il file, il suo tipo MIME e messaging_product=whatsapp, e la risposta è {"id": "<MEDIA_ID>"}. I file caricati vengono cifrati e conservati per 30 giorni, salvo che li eliminiate prima.

Sull'endpoint WhatsApp di OmniChannels.ai un messaggio media accetta mediaUrl (un URL HTTPS pubblico) oppure mediaFile (un file caricato con la richiesta), con la didascalia in content. Consultate la documentazione dell'API WhatsApp. Chiedete al nostro team come il vostro account gestisce l'archiviazione e il riutilizzo dei media per gli invii di grandi dimensioni.

Per quanto tempo restano validi gli ID media?

Meta indica 30 giorni per un ID restituito da un upload e 7 giorni per un ID ricevuto in un webhook in entrata. L'URL di download restituito per un ID scade dopo 5 minuti.

Conseguenze pratiche:

• Non conservate in cache un ID media per mesi. Tenete il file originale e ricaricatelo quando un ID viene rifiutato.
• Scaricate i file in entrata non appena arriva l'evento e tenete una copia vostra.
• Non salvate mai un URL di download ottenuto; chiedetene uno nuovo quando serve.

Posso aggiungere didascalie ai messaggi media?

Sì. I messaggi con immagine, video e documento accettano una didascalia facoltativa fino a 1.024 caratteri, secondo i riferimenti ai messaggi di Meta. Le didascalie sono testo semplice accanto al file.

I messaggi audio e gli sticker non hanno didascalia in questo modello. Se vi servono parole insieme a un vocale, inviate accanto un breve messaggio di testo. All'interno della finestra di assistenza clienti le didascalie sono libere; al di fuori, il media deve viaggiare in un template approvato.

Come funzionano i media nei modelli di messaggio?

Un template può avere un'immagine, un video o un documento nell'header, e quell'header viene fissato quando create il template. Quando inviate un template per l'approvazione fornite un file di esempio, e al momento dell'invio potete fornire il file effettivo.

Nella nostra API, headerFormat può essere IMAGE, VIDEO o DOCUMENT alla creazione, headerFile contiene l'esempio e mediaUrl al momento dell'invio sostituisce il media dell'header. Per i requisiti dei file di esempio consultate la documentazione di Meta sui template. Vedi categorie di template e approvazione ed esempi di template.

Come scarico i media che un cliente mi invia?

I media in entrata arrivano come webhook con un ID media; lo risolvete in un URL e lo scaricate con autorizzazione.

1. Leggete l'ID media dall'evento del messaggio in entrata.
2. Richiedete l'URL del media per quell'ID. La risposta di Meta include url, mime_type, sha256 e file_size.
3. Inviate una GET a quell'URL con l'header Authorization: Bearer <token>. Senza il token la richiesta fallisce.
4. Controllate l'header Content-Type e il valore sha256, poi salvate il file.
5. In caso di 404, richiedete un nuovo URL e riprovate; se fallisce ancora, rinnovate il token di accesso.

La dimensione massima dei media in entrata di Meta sulla Cloud API è 100 MB. Un file più grande genera un webhook con il codice di errore 131052; chiedete al cliente di inviare un file più piccolo o di condividerlo in un altro modo. Analizzate ogni file con un antivirus prima di aprirlo internamente. Vedi la guida ai webhook e verificate con il vostro tecnico di attivazione come vengono consegnati i media in entrata sul vostro account.

Esempio pratico: una clinica dentistica che invia referti

"Nile Smile Clinic" (fittizia) al Cairo invia cartoncini di appuntamento e referti radiografici.

1. I cartoncini di appuntamento sono immagini PNG da 300 KB con una didascalia di due righe. Ben sotto i 5 MB.
2. I referti dei trattamenti sono PDF da 2 a 8 MB, chiamati report-2026-0381.pdf, inviati come documenti.
3. Un video di presentazione della clinica da 25 MB è troppo grande per il video. Il team lo ricodifica come MP4 H.264/AAC sotto i 16 MB con faststart.
4. I pazienti inviano foto delle prescrizioni. La casella scarica ogni file subito, perché l'ID in entrata scade dopo 7 giorni.
5. Un saluto vocale viene esportato come OGG Opus mono, perché le altre varianti di OGG vengono rifiutate.

Quali sono gli errori più comuni?

• Giudicare solo dalla dimensione. Un'immagine da 3 MB nel formato colore sbagliato o un video con il codec sbagliato fallisce comunque.
• Tipo MIME non corrispondente. Un .jpg servito come application/octet-stream è una causa classica dell'errore 131053.
• Linkare un URL lento o privato, come un link firmato scaduto o una pagina dietro login.
• Affidarsi a un vecchio ID media. Gli ID scadono dopo 30 giorni.
• Ignorare la scadenza dei file in entrata. I file dei clienti vanno salvati entro 7 giorni.
• WebP animato come immagine. Viene rifiutato; usate uno sticker o un video.
• I limiti cambiano. Ricontrollate il riferimento di Meta prima di codificare le validazioni.

Come vi aiuta OmniChannels.ai

OmniChannels.ai invia messaggi WhatsApp con immagini, video, audio, documenti e sticker tramite un'unica API, con un link pubblico o un file caricato e una didascalia, e mostra media e allegati nella casella condivisa. BroadNet è un Business Solution Provider ufficiale di Meta, quindi i template con header immagine, video o documento possono essere creati e monitorati con lo stato di approvazione. Leggete la documentazione dell'API WhatsApp e errori e limiti, oppure scoprite il canale WhatsApp.