Sign inGet started

WhatsApp-Dokumentnachrichten

Eine Dokumentnachricht enthält eine öffentliche URL, die WhatsApp beim Senden abruft, mit einer optionalen Beschriftung und einem optionalen Dateinamen. Sie ist der größte Medientyp und der einzige, der sowohl eine Beschriftung als auch einen Dateinamen enthält.

Dokument senden

Setzen Sie 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);
Die vollständige Struktur fügt caption und filename hinzu:
Codebeispiel
{
  "to": "+16505551234",
  "from": "+13124495648",
  "document": {
    "url": "https://cdn.example.com/invoices/a1b2c3.pdf",
    "caption": "Your invoice for order A1B2C3",
    "filename": "invoice-a1b2c3.pdf"
  }
}
from ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete.

Beschränkungen

FeldGrenzwertGeprüft von
Dateigröße100 MBnur WhatsApp, beim Abruf (async)
DateitypPDF, Word, Excel, PowerPoint oder Klartext werden im WhatsApp-Client zuverlässig dargestellt; andere Typen werden übertragen, aber nicht unterstütztnur WhatsApp, beim Abruf (async)
captionbis zu 1024 ZeichenBird, bei Annahme (422)
filename1 bis 100 ZeichenBird, bei Annahme (422); dieses Limit ist Birds eigenes, da WhatsApp kein Dateinamenlimit dokumentiert
urlabsolut, https, hat einen Host, kein rohes LeerzeichenBird, bei Annahme (422)
Bird prüft die Form der URL sowie die Länge der Beschriftung und des Dateinamens, bevor etwas in die Warteschlange gestellt wird. Dateigröße und -typ werden nicht geprüft; das kann nur der eigene Abruf von WhatsApp beim Senden. Siehe im Hub Medien per URL senden und Wenn Medien fehlschlagen.

Ein eingehendes Dokument lesen

Ein eingehendes Dokument enthält dasselbe document-Objekt, zusätzlich ein id und mime_type, die Bird durch Abruf der Datei ermittelt hat. Beide fehlen bei einem ausgehenden Rücklesen, da Bird die gesendete Datei nie selbst abgerufen hat, und filename bei einem eingehenden Dokument enthält das, was das Gerät des Kontakts geliefert hat. Siehe WhatsApp-Dokumente empfangen für das vollständige eingehende Lesen, die whatsapp.received-Payload und worauf Sie achten sollten.

Beschränkungen und Fehlerfälle

  • Das Kundenservice-Fenster muss offen sein. Dokumente sind Service-Nachrichten und nur innerhalb eines offenen Fensters zustellbar; siehe im Hub Kundenservice-Fenster.
  • Bird lehnt http ab; WhatsApp selbst würde es abrufen. Siehe im Hub Medien per URL senden für die vollständige Formprüfung.
  • Ein fehlgeschlagener Abruf wird trotzdem berechnet, und dieser Medientyp ist am ehesten davon betroffen. Mit 100 MB ist ein Dokument das Größte, was Sie senden können, und Bird prüft bei der Annahme nichts an den tatsächlichen Bytes. Siehe im Hub Wenn Medien fehlschlagen für media_rejected und die Tatsache, dass bei Fehlschlag trotzdem Kosten anfallen. Der eigene Ablehnungstext von Dokumenten aus WhatsApp wurde nicht unabhängig gemessen wie der von Bildern, daher ist das Mapping als per Symmetrie abgeleitet zu betrachten, nicht als pro Ursache bestätigt.
  • Das Weglassen von filename bedeutet nicht, dass der Empfänger keinen Namen sieht. WhatsApp leitet einen aus dem URL-Pfad ab, was ein undurchsichtiger Hash oder Slug sein kann statt etwas Lesbarem. Setzen Sie filename explizit, um zu steuern, was tatsächlich angezeigt wird.
  • Das 100-Zeichen-Limit für filename ist Birds eigene Wahl, keine WhatsApp-Beschränkung. WhatsApp dokumentiert überhaupt kein Dateinamenlängenlimit.
  • WhatsApp speichert eine abgerufene URL etwa 10 Minuten im Cache. Wenn Sie dieselbe URL innerhalb dieses Zeitraums erneut senden, wird der erste Abruf wiederverwendet; ändern Sie die URL, um einen neuen Abruf zu erzwingen.

Nächste Schritte

  • WhatsApp-Service-Nachrichten: das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten gemeinsam haben
  • Bilder: für ein Foto oder eine Grafik statt einer Datei
  • Templates: für Nachrichten, die Sie senden können, wenn das Fenster geschlossen ist
  • WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sichere Wiederholungsversuche