Sign inGet started

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);
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

VeldGrensAfgedwongen door
Bestandsgrootte100 MBalleen WhatsApp, bij ophalen (async)
BestandstypePDF, Word, Excel, PowerPoint of platte tekst worden betrouwbaar weergegeven in de WhatsApp-client; andere typen worden verzonden maar niet ondersteundalleen WhatsApp, bij ophalen (async)
captionmaximaal 1024 tekensBird, bij acceptatie (422)
filename1 tot 100 tekensBird, bij acceptatie (422); deze limiet is eigen aan Bird, aangezien WhatsApp geen bestandsnaamlimiet documenteert
urlabsoluut, https, heeft een host, geen ongecodeerde spatieBird, 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