# 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`: **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/de-de/dokumentation/guides/whatsapp/message-types/documents.ts.md) · [Python](/de-de/dokumentation/guides/whatsapp/message-types/documents.py.md) · [Go](/de-de/dokumentation/guides/whatsapp/message-types/documents.go.md) · [PHP](/de-de/dokumentation/guides/whatsapp/message-types/documents.php.md) · [CLI](/de-de/dokumentation/guides/whatsapp/message-types/documents.cli.md) · [MCP](/de-de/dokumentation/guides/whatsapp/message-types/documents.mcp.md) · [cURL](/de-de/dokumentation/guides/whatsapp/message-types/documents.curl.md) Die vollständige Struktur fügt `caption` und `filename` hinzu: ```json { "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 | Feld | Grenzwert | Geprüft von | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Dateigröße | 100 MB | nur WhatsApp, beim Abruf (async) | | Dateityp | PDF, Word, Excel, PowerPoint oder Klartext werden im WhatsApp-Client zuverlässig dargestellt; andere Typen werden übertragen, aber nicht unterstützt | nur WhatsApp, beim Abruf (async) | | `caption` | bis zu 1024 Zeichen | Bird, bei Annahme (`422`) | | `filename` | 1 bis 100 Zeichen | Bird, bei Annahme (`422`); dieses Limit ist Birds eigenes, da WhatsApp kein Dateinamenlimit dokumentiert | | `url` | absolut, `https`, hat einen Host, kein rohes Leerzeichen | Bird, 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](/docs/guides/whatsapp/message-types#sending-media-by-url) und [Wenn Medien fehlschlagen](/docs/guides/whatsapp/message-types#when-media-fails). ## 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](/docs/guides/whatsapp/receiving-whatsapp/documents) 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](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird lehnt `http` ab; WhatsApp selbst würde es abrufen.** Siehe im Hub [Medien per URL senden](/docs/guides/whatsapp/message-types#sending-media-by-url) 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](/docs/guides/whatsapp/message-types#when-media-fails) 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](/docs/guides/whatsapp/message-types): das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten gemeinsam haben - [Bilder](/docs/guides/whatsapp/message-types/images): für ein Foto oder eine Grafik statt einer Datei - [Templates](/docs/guides/whatsapp/templates): für Nachrichten, die Sie senden können, wenn das Fenster geschlossen ist - [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): der Request-Envelope, das `202`-Modell und sichere Wiederholungsversuche ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/products/whatsapp) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)