WhatsApp-documentberichten
Een documentbericht bevat een publieke URL die WhatsApp ophaalt bij het verzenden, met een optioneel bijschrift en een optionele bestandsnaam. Het is het grootste mediatype, en het enige dat zowel een bijschrift als een bestandsnaam meestuurt.
Een document versturen
Stel document.url in:
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"
}
}'De volledige structuur voegt caption en filename toe:
Codevoorbeeld
{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf",
"caption": "Your invoice for order A1B2C3",
"filename": "invoice-a1b2c3.pdf"
}
}from is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, geen door Bird beheerd nummer.
Limieten
| Veld | Grens | Afgedwongen door |
|---|---|---|
| Bestandsgrootte | 100 MB | alleen WhatsApp, bij ophalen (async) |
| Bestandstype | PDF, Word, Excel, PowerPoint of platte tekst worden betrouwbaar weergegeven in de WhatsApp-client; andere typen worden verzonden maar niet ondersteund | alleen WhatsApp, bij ophalen (async) |
| caption | maximaal 1024 tekens | Bird, bij acceptatie (422) |
| filename | 1 tot 100 tekens | Bird, bij acceptatie (422); deze limiet is eigen aan Bird, aangezien WhatsApp geen bestandsnaamlimiet documenteert |
| url | absoluut, https, heeft een host, geen ongecodeerde spatie | Bird, bij acceptatie (422) |
Bird controleert de vorm van de URL en de lengte van het bijschrift en de bestandsnaam voordat er iets in de wachtrij wordt geplaatst. Het controleert niet de werkelijke grootte of het type van het bestand; dat kan alleen de eigen ophaalactie van WhatsApp bij het verzenden. Zie de hub's media versturen via URL en wanneer media mislukt.
Een inkomend document lezen
Een inkomend document bevat hetzelfde document-object, plus een id en mime_type die Bird heeft geleerd door het bestand op te halen. Beide ontbreken bij het teruglezen van een uitgaand bericht, omdat Bird het verzonden bestand nooit zelf ophaalde, en filename bij een inkomend bericht is wat het apparaat van de contactpersoon meestuurde. Zie WhatsApp-documenten ontvangen voor het volledige inkomende bericht, de whatsapp.received-payload en waar je op moet letten.
Limieten en faalscenario's
- Het klantenservicevenster moet open zijn. Documenten zijn serviceberichten die alleen binnen een open venster afgeleverd kunnen worden; zie de hub's klantenservicevenster.
- Bird weigert http; WhatsApp zelf zou het ophalen. Zie de hub's media versturen via URL voor de volledige vormcontrole.
- Een mislukt ophaalverzoek wordt toch in rekening gebracht, en dit is het mediatype waar je daar het vaakst tegenaan loopt. Met 100 MB is een document het grootste dat je kunt versturen, en Bird controleert bij acceptatie niets aan de werkelijke bytes. Zie de hub's wanneer media mislukt voor media_rejected en het feit dat er bij falen toch kosten in rekening worden gebracht. De eigen weigeringstekst van documenten van WhatsApp is niet onafhankelijk gemeten zoals bij afbeeldingen, dus beschouw de mapping als afgeleid door symmetrie in plaats van bevestigd per oorzaak.
- Het weglaten van filename betekent niet dat de ontvanger geen naam ziet. WhatsApp leidt er een af uit het URL-pad, wat een ondoorzichtige hash of slug kan zijn in plaats van iets leesbaars. Stel filename expliciet in om te bepalen wat er daadwerkelijk wordt getoond.
- De limiet van 100 tekens voor filename is een eigen keuze van Bird, geen WhatsApp-limiet. WhatsApp documenteert helemaal geen limiet voor de bestandsnaamlengte.
- WhatsApp cachet een opgehaalde URL voor ongeveer 10 minuten. Als je dezelfde URL binnen dat venster opnieuw verstuurt, wordt het eerste ophaalresultaat opnieuw gebruikt; varieer de URL om een nieuw ophaalverzoek te forceren.
Vervolgstappen
- WhatsApp-serviceberichten: het klantenservicevenster en het model dat elk servicebericht deelt
- Afbeeldingen: voor een foto of afbeelding in plaats van een bestand
- Templates: voor berichten die je kunt versturen als het venster gesloten is
- WhatsApp-berichten versturen: de request-envelope, het 202-model en veilig opnieuw proberen
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channelBegrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builderOntdek de mogelijkheidWhatsApp
Probeer de oefening en ontvang een implementatieoverzicht