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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
document={"url": "https://cdn.example.com/invoices/a1b2c3.pdf"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Document: &bird.WhatsAppDocumentSend{Url: "https://cdn.example.com/invoices/a1b2c3.pdf"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$document = (new WhatsAppMessageSendRequestDocument())
->setUrl('https://cdn.example.com/invoices/a1b2c3.pdf');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
document: $document,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--document https://cdn.example.com/invoices/a1b2c3.pdf \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
}
}'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
| Campo | Vincolo | Applicato da |
|---|---|---|
| Dimensione file | 100 MB | Solo WhatsApp, al fetch (asincrono) |
| Tipo di file | PDF, Word, Excel, PowerPoint o testo semplice vengono visualizzati in modo affidabile nel client WhatsApp; gli altri tipi vengono trasmessi ma non sono supportati | Solo WhatsApp, al fetch (asincrono) |
| caption | Fino a 1024 caratteri | Bird, all'accettazione (422) |
| filename | Da 1 a 100 caratteri | Bird, all'accettazione (422); questo limite è una scelta di Bird, dato che WhatsApp non documenta alcun limite per il nome file |
| url | Assoluto, https, con host, senza spazi grezzi | Bird, 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
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione