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.

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.

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 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.

Siehe das Kundenservice-Fenster für den vollständigen Lebenszyklus: wie das Fenster geöffnet wird, was es zurücksetzt und wie es verfolgt wird.

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:

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.

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.

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 behandelt das Lesen eingehender Nachrichten über die API, den Abruf der von einem Kontakt gesendeten Medien und den whatsapp.received-Webhook.