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

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 von Metas offenem 24-Stunden-Kundenservice-Fenster 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.

Für die Prüfung bei Annahme erfasst die Bird API das Fenster ausschließlich anhand eingehender Nachrichten. Ein Anruf kann Metas Fenster öffnen, während das von Bird erfasste Fenster geschlossen bleibt. Bevor Sie frei formulierte Inhalte über Bird senden, bitten Sie den Kontakt, eine Nachricht an die verbundene Geschäftsnummer zu senden, die Sie als from verwenden werden. Verwenden Sie beim Antworten das Feld from der eingehenden Nachricht als Empfänger und das Feld to als Absender. Enthält die eingehende Nachricht nur eine bsuid, adressieren Sie diese ID; eine anderweitig ermittelte Telefonnummer teilt deren Fenster nicht.

Eine Service-Nachricht, die bei geschlossenem, von Bird erfasstem Fenster gesendet wird, wird sofort abgelehnt: Der Request gibt einen 422 E15044 WhatsAppServiceWindowClosed zurück, und es wird nichts erstellt oder berechnet. Senden Sie stattdessen ein geeignetes, genehmigtes Template; Templates erfordern kein offenes Fenster, und die Antwort des Kontakts öffnet es erneut. Schließt sich das Fenster zwischen Annahme und Versand, schlägt die Nachricht ebenfalls fehl, aber asynchron: Sie erreicht failed mit service_window_expired auf last_error.

Kann die API ihre Prüfung des Service-Fensters nicht abschließen, kann der Request dennoch angenommen werden, damit WhatsApp ihn beim Versand prüft. Eine abgeschlossene Prüfung, die kein offenes Fenster findet, lehnt den Request ab. Ein 202 bestätigt die Annahme; prüfen Sie den Status der Nachricht, um das Zustellergebnis zu erfahren.

Jede Service-Nachricht erfordert außerdem from, eine Nummer, die Ihrem Workspace gehört. Die verwalteten Nummern von Bird können sie nicht übermitteln, daher benötigen Sie 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.

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 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: der Request-Umschlag, das 202-Modell und sichere Wiederholungen
• Interaktive Nachrichten: die sechs Typen, die ein Empfänger antippen kann
• WhatsApp-Nachrichten empfangen: eingehende Nachrichten, Medien und der whatsapp.received-Webhook
• WhatsApp-Templates: die Nachrichten, die Sie auch bei geschlossenem Fenster noch senden können