Sign inGet started

Messaggi documento WhatsApp

Un messaggio documento trasporta un URL pubblico che WhatsApp recupera al momento dell'invio, con una didascalia facoltativa e un nome file facoltativo. È il tipo di media più grande e l'unico che trasporta sia una didascalia sia un nome file.

Inviare un documento

Imposta document.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" },
});
console.log(msg.id, msg.status);
La forma completa aggiunge caption e filename:
Esempio di codice
{
  "to": "+16505551234",
  "from": "+13124495648",
  "document": {
    "url": "https://cdn.example.com/invoices/a1b2c3.pdf",
    "caption": "Your invoice for order A1B2C3",
    "filename": "invoice-a1b2c3.pdf"
  }
}
from è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird.

Limiti

CampoVincoloApplicato da
Dimensione file100 MBSolo WhatsApp, al fetch (asincrono)
Tipo di filePDF, Word, Excel, PowerPoint o testo semplice vengono visualizzati in modo affidabile nel client WhatsApp; gli altri tipi vengono trasmessi ma non sono supportatiSolo WhatsApp, al fetch (asincrono)
captionFino a 1024 caratteriBird, all'accettazione (422)
filenameDa 1 a 100 caratteriBird, all'accettazione (422); questo limite è una scelta di Bird, dato che WhatsApp non documenta alcun limite per il nome file
urlAssoluto, https, con host, senza spazi grezziBird, all'accettazione (422)
Bird controlla la forma dell'URL e la lunghezza della didascalia e del nome file prima di accodare qualsiasi cosa. Non controlla la dimensione o il tipo effettivi del file; solo il fetch di WhatsApp al momento dell'invio può farlo. Consulta le pagine dell'hub invio di media tramite URL e quando un media fallisce.

Leggere un documento in ingresso

Un documento in ingresso trasporta lo stesso oggetto document, più un id e un mime_type che Bird ha appreso recuperando il file. Entrambi sono assenti in una rilettura in uscita, perché Bird non ha mai recuperato il file che ha inviato, e filename in un documento in ingresso è qualsiasi valore fornito dal dispositivo del contatto. Consulta Ricezione di documenti WhatsApp per la lettura completa in ingresso, il payload whatsapp.received e gli aspetti a cui prestare attenzione.

Limiti e modalità di errore

  • La finestra del servizio clienti deve essere aperta. I documenti sono messaggi di servizio, recapitabili solo all'interno di una finestra aperta; consulta la pagina dell'hub finestra del servizio clienti.
  • Bird rifiuta http; WhatsApp stesso lo recupererebbe. Consulta la pagina dell'hub invio di media tramite URL per il controllo completo della forma.
  • Un fetch rifiutato viene comunque addebitato, e questo è il tipo di media che più probabilmente lo incontra. Con 100 MB, un documento è l'elemento più grande che puoi inviare, e Bird non controlla nulla sui byte effettivi all'accettazione. Consulta la pagina dell'hub quando un media fallisce per media_rejected e il fatto che l'addebito avviene anche in caso di errore. Il testo di rifiuto specifico per i documenti da parte di WhatsApp non è stato misurato in modo indipendente come per le immagini, quindi considera la mappatura come inferita per simmetria piuttosto che confermata per ogni causa.
  • Omettere filename non significa che il destinatario non veda alcun nome. WhatsApp ne ricava uno dal percorso dell'URL, che può essere un hash opaco o uno slug anziché qualcosa di leggibile. Imposta filename esplicitamente per controllare ciò che viene effettivamente mostrato.
  • Il limite di 100 caratteri per filename è una scelta di Bird, non un limite di WhatsApp. WhatsApp non documenta alcun limite di lunghezza per il nome file.
  • WhatsApp mette in cache un URL recuperato per circa 10 minuti. Reinviare lo stesso URL all'interno di quella finestra serve il primo fetch; modifica l'URL per forzarne uno nuovo.

Passaggi successivi

  • Messaggi di servizio WhatsApp: la finestra del servizio clienti e il modello condiviso da ogni messaggio di servizio
  • Immagini: per una foto o un elemento grafico al posto di un file
  • Template: per i messaggi da inviare quando la finestra è chiusa
  • Invio di messaggi WhatsApp: la struttura della richiesta, il modello 202 e i tentativi sicuri di riprovare