# WhatsApp-Service-Nachrichten Eine **Service-Nachricht** ist alles, was Sie senden und kein vorab genehmigtes Template ist: der frei formulierte Inhalt, den ein Unternehmen innerhalb einer offenen Konversation sendet. `POST /v1/whatsapp/messages` trägt genau einen von neun Inhaltstypen für Service-Nachrichten oder ein Template. Diese Seite behandelt, was die neun Typen gemeinsam haben; die eigene Seite jedes Typs beschreibt sein Nachrichtenformat und seine spezifischen Einschränkungen. ## Die Inhaltstypen | Typ | Feld | Was es trägt | Einsatzzweck | | -------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | [Klartext](/docs/guides/whatsapp/message-types/plain-text) | `text` | Ein Text mit bis zu 4.096 Zeichen, mit optionaler Link-Vorschau | Sie senden eine Nachricht ohne Anhang | | [Bilder](/docs/guides/whatsapp/message-types/images) | `image` | Eine öffentliche Bild-URL und eine optionale Bildunterschrift | Sie senden ein Foto oder eine Grafik | | [Video](/docs/guides/whatsapp/message-types/video) | `video` | Eine öffentliche Video-URL und eine optionale Bildunterschrift | Sie senden einen Videoclip | | [Audio](/docs/guides/whatsapp/message-types/audio) | `audio` | Eine öffentliche Audio-URL, optional als Sprachnachricht dargestellt | Sie senden eine Sprachnachricht oder einen Audioclip | | [Sticker](/docs/guides/whatsapp/message-types/stickers) | `sticker` | Eine öffentliche WebP-Bild-URL | Sie senden einen Sticker | | [Dokumente](/docs/guides/whatsapp/message-types/documents) | `document` | Eine öffentliche Datei-URL, eine optionale Bildunterschrift und ein optionaler Dateiname | Sie senden ein PDF, eine Tabelle oder eine andere Datei | | [Standort](/docs/guides/whatsapp/message-types/location) | `location` | Breiten- und Längengrad, mit optionalem Namen und Adresse | Sie senden eine Markierung, z. B. einen Abholpunkt | | [Kontaktkarten](/docs/guides/whatsapp/message-types/contact-cards) | `contact_cards` | Ein bis fünf Kontaktkarten, jeweils mit Name und beliebigen Nummern, E-Mails, Websites oder Adressen | Sie teilen die Daten einer Person, z. B. die Nummer eines Kollegen | | [Interaktive Nachrichten](/docs/guides/whatsapp/message-types/interactive) | `interactive` | Nachrichtentext plus ein Button, ein Menü, ein Link, eine Karte oder eine Anfrage nach Standort oder Kontakt | Sie möchten, dass der Empfänger etwas antippt, statt eine freie Antwort zu tippen | Ein Request enthält genau eines von `template` oder eines dieser neun Felder. Ein Request ohne eines davon oder mit mehr als einem wird mit einer `422` abgelehnt. ## Das Kundenservice-Fenster Eine Service-Nachricht, also jeder der neun oben genannten Typen, wird nur innerhalb eines offenen 24-Stunden-Kundenservice-Fensters zugestellt. Der Kontakt öffnet dieses Fenster, indem er Ihrer Geschäftsnummer eine Nachricht sendet oder sie anruft, und jede weitere Nachricht von ihm setzt es auf 24 Stunden zurück. Eine Service-Nachricht in ein geschlossenes Fenster wird sofort abgelehnt: Der Request gibt einen `422` [`E15044`](/docs/api/errors/E15044) `WhatsAppServiceWindowClosed` zurück, und es wird nichts erstellt oder berechnet. Senden Sie stattdessen ein genehmigtes Template; es erreicht den Kontakt unabhängig vom Fenster, und seine Antwort öffnet es erneut. Ein Fenster, das sich im Moment zwischen Annahme und Versand schließt, schlägt dennoch fehl, aber asynchron: Die Nachricht erreicht `failed` mit `service_window_expired` auf `last_error`. Die Prüfung bei Annahme erfolgt nach dem Best-Effort-Prinzip, nicht als Garantie: **Das Gate schlägt offen fehl**, d. h. ein Cache-Miss oder Lesefehler lässt den Versand durch, statt ihn zu blockieren. Ein `202` ist daher kein Beweis, dass das Fenster beim Versand offen war; das maßgebliche Signal ist der eigene Status der Nachricht, nicht die Annahmeantwort. Jede Service-Nachricht erfordert außerdem `from`, eine Nummer, die Ihrem Workspace gehört. Die verwalteten Nummern von Bird können sie nicht tragen, daher benötigt eine Service-Nachricht zuerst eine eigene verbundene Nummer; siehe [Einrichtung der Telefonnummer](/docs/guides/whatsapp/phone-number-setup). Siehe [das Kundenservice-Fenster](/docs/knowledge-base/whatsapp/customer-service-window) für den vollständigen Lebenszyklus: wie das Fenster geöffnet wird, was es zurücksetzt und wie es verfolgt wird. ## Medienversand per URL `image`, `video`, `audio`, `sticker` und `document` nehmen alle eine `url`, die auf eine Datei verweist, die WhatsApp zum Sendezeitpunkt abruft, statt einer Datei, die Sie zu Bird hochladen. Bird prüft die Form der URL bei der Annahme, bevor etwas eingereiht wird: - Nicht leer und parsebar, mit einem Host und ohne rohes Leerzeichen - Schema ist `https` Eine `http`-URL wird bei der Annahme mit einem `422` abgelehnt, obwohl WhatsApp sie problemlos abrufen würde. Das ist die Richtlinie von Bird, keine Einschränkung, die WhatsApp auferlegt. Bird prüft weder die Dateigröße noch den MIME-Typ oder ob die URL erreichbar ist. WhatsApp ruft die URL selbst ab, sobald die Nachricht versendet wird; eine signierte URL muss also über diesen Zeitpunkt hinaus gültig bleiben, nicht nur zum Zeitpunkt Ihres Requests. Eine private oder abgelaufene URL schlägt fehl, sobald WhatsApp versucht, sie abzurufen. WhatsApp speichert eine abgerufene URL außerdem für etwa 10 Minuten im Cache, sodass ein erneutes Senden derselben URL innerhalb dieses Zeitraums den ersten Abruf wiederverwendet, statt erneut abzurufen. ## Wenn Medien fehlschlagen Ein Medienversand folgt demselben asynchronen Pfad wie jede WhatsApp-Nachricht: Bird gibt `202` zurück und nimmt die Nachricht an, dann ruft WhatsApp die URL beim Versand ab. Wenn dieser Abruf fehlschlägt, erreicht die Nachricht `failed` mit `media_rejected` auf `last_error`, was Metas `131053` darunter entspricht. `media_rejected` ist ein Sammelfehler für eine zu große Datei, einen `404`, einen DNS-Fehler und einen falschen MIME-Typ gleichermaßen; Bird unterscheidet nicht weiter, erwarten Sie also keinen eigenen Code pro Ursache. Ein asynchron fehlgeschlagener Medienversand wird trotzdem berechnet. Die Abrechnung erfolgt, wenn Bird den angenommenen Versand verarbeitet, bevor WhatsApp die URL jemals abruft, und es gibt keinen Erstattungspfad, sobald die Belastung erfolgt ist. Planen Sie entsprechend: Eine Nachricht, die später in `media_rejected` fehlschlägt, hat bereits dasselbe gekostet wie eine zugestellte. ## Lesen, was ein Kontakt gesendet hat Eine eingehende Nachricht trägt einen der gleichen neun Typen, sodass das Feld, das Sie lesen, dem vom Kontakt verwendeten Typ entspricht. Kontaktkarten werden im selben `contact_cards`-Feld zurückgegeben, egal ob der Kontakt eine geteilt oder Sie eine gesendet haben. [WhatsApp-Nachrichten empfangen](/docs/guides/whatsapp/receiving-whatsapp) behandelt das Lesen eingehender Nachrichten über die API, den Abruf der von einem Kontakt gesendeten Medien und den `whatsapp.received`-Webhook. ## Nächste Schritte - [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): der Request-Umschlag, das `202`-Modell und sichere Wiederholungen - [Interaktive Nachrichten](/docs/guides/whatsapp/message-types/interactive): die sechs Typen, die ein Empfänger antippen kann - [WhatsApp-Nachrichten empfangen](/docs/guides/whatsapp/receiving-whatsapp): eingehende Nachrichten, Medien und der `whatsapp.received`-Webhook - [WhatsApp-Templates](/docs/guides/whatsapp/templates): die Nachrichten, die Sie auch bei geschlossenem Fenster noch senden können ## 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)