WhatsApp-serviceberichten

Een servicebericht is alles wat je stuurt dat geen vooraf goedgekeurd template is: de vrije inhoud die een bedrijf verstuurt binnen een open gesprek. POST /v1/whatsapp/messages bevat precies één van negen inhoudstypen voor serviceberichten, of een template. Deze pagina behandelt wat de negen typen gemeen hebben; de eigen pagina van elk type behandelt de berichtstructuur en specifieke limieten.

Een request bevat precies één van template of één van deze negen velden. Een request dat geen van beide bevat, of meer dan één, wordt geweigerd met een 422.

Een servicebericht, oftewel een van de negen bovenstaande typen, wordt alleen bezorgd binnen een open 24-uurs klantenservicevenster. Het contact opent dat venster door je zakelijke nummer te berichten of te bellen, en elk volgend bericht van hen reset het naar 24 uur.

Een servicebericht dat naar een gesloten venster wordt gestuurd, wordt direct geweigerd: het request retourneert een 422 E15044 WhatsAppServiceWindowClosed, en er wordt niets aangemaakt of in rekening gebracht. Stuur in plaats daarvan een goedgekeurd template; dat bereikt het contact ongeacht het venster, en hun antwoord heropent het. Een venster dat sluit op het moment tussen accepteren en verzenden mislukt alsnog, maar asynchroon: het bericht bereikt failed met service_window_expired op last_error.

De controle bij acceptatie is best effort, geen garantie: de poort faalt open, dus een cachemiss of een leesfout laat de verzending door in plaats van te blokkeren. Een 202 is daarom geen bewijs dat het venster open was toen de verzending plaatsvond; het definitieve signaal is de status van het bericht zelf, niet het acceptatieantwoord.

Elk servicebericht vereist ook from, een nummer dat je werkruimte bezit. De beheerde nummers van Bird kunnen dat niet dragen, dus een servicebericht heeft eerst een eigen gekoppeld nummer nodig; zie Telefoonnummer instellen.

Zie het klantenservicevenster voor de volledige levenscyclus: hoe het venster opent, wat het reset en hoe het wordt bijgehouden.

image, video, audio, sticker en document nemen allemaal een url die naar een bestand wijst dat WhatsApp op het moment van verzending ophaalt, in plaats van een bestand dat je uploadt naar Bird. Bird controleert de vorm van de URL bij acceptatie, voordat er iets in de wachtrij wordt geplaatst:

Een http-URL wordt bij acceptatie geweigerd met een 422, ook al zou WhatsApp deze prima ophalen. Dat is beleid van Bird, niet een beperking die WhatsApp oplegt.

Bird controleert niet de bestandsgrootte, het MIME-type of of de URL bereikbaar is. WhatsApp haalt de URL zelf op zodra het bericht wordt verzonden, dus een ondertekende URL moet geldig blijven voorbij dat moment, niet alleen op het moment dat je het request verstuurt; een privé- of verlopen URL mislukt zodra WhatsApp probeert deze op te halen. WhatsApp cachet een opgehaalde URL ook voor ongeveer 10 minuten, dus als je dezelfde URL binnen dat venster opnieuw verstuurt, wordt de eerste fetch opnieuw geserveerd in plaats van opnieuw opgehaald.

Een mediaverzending volgt hetzelfde asynchrone pad als elk WhatsApp-bericht: Bird retourneert 202 en accepteert het bericht, waarna WhatsApp de URL ophaalt bij verzending. Als die fetch mislukt, bereikt het bericht failed met media_rejected op last_error, wat onderliggend Meta's 131053 is.

media_rejected is een overkoepelende code voor een te groot bestand, een 404, een DNS-fout en een verkeerd MIME-type; Bird splitst het niet verder op, dus verwacht geen aparte code per oorzaak.

Een asynchroon mislukte mediaverzending wordt toch in rekening gebracht. De afrekening vindt plaats wanneer Bird de geaccepteerde verzending verwerkt, voordat WhatsApp ooit de URL ophaalt, en er is geen restitutiepad zodra die afrekening is geboekt. Houd daar rekening mee: een bericht dat later mislukt in media_rejected kost evenveel als een bericht dat is bezorgd.

Een inkomend bericht bevat een van dezelfde negen typen, dus het veld dat je leest komt overeen met het type dat het contact heeft gebruikt. Contactkaarten worden via hetzelfde contact_cards-veld teruggelezen, ongeacht of het contact er een deelde of jij er een stuurde. WhatsApp-berichten ontvangen behandelt het lezen van inkomende berichten via de API, het ophalen van media die een contact heeft gestuurd, en de whatsapp.received-webhook.