WhatsApp Catalog API: bouw de workflow na de producttik

De WhatsApp Catalog API kan een product in een gesprek plaatsen, maar maakt op zichzelf nog geen betrouwbaar bestelproces. De relevante ontwerpvraag begint na de producttik: welke identifier reist mee, wie bezit de aanvraag, wanneer wordt voorraad gecontroleerd, wat verandert een inkomende order in uitvoerbaar werk en hoe herstelt het team wanneer de werkelijkheid afwijkt van de catalogus?

Deze gids behandelt die operationele vraag. De actuele catalogusberichten en webhookobjecten van Meta vormen de technische grens; daarbinnen bouwen we een proces dat een commerceteam werkelijk kan testen. De hoofdregel: beschouw de catalogus als een oppervlak voor productontdekking en elke webhook als bewijs van klantintentie, niet als bewijs dat voorraad gereserveerd, betaling ontvangen of fulfillment gestart is.

Wat de WhatsApp Catalog API werkelijk levert

Meta's officiële collectie beschrijft twee bruikbare interactieve berichtvormen. Een bericht met één product gebruikt type: interactive, subtype product, een catalog_id en een product_retailer_id. Een multiproductbericht gebruikt subtype product_list, één catalog_id en secties met items die via product_retailer_id worden geïdentificeerd (single-product request, multi-product request).

Meta documenteert ook catalogustemplates met een CATALOG-knop. Zo'n template opent de bedrijfscatalogus in WhatsApp, maar vervangt geen product-, voorraad-, order- of betaalsysteem (catalog template request). Kies het berichttype op basis van de klanttaak, niet op basis van de meest opvallende presentatie.

De inkomende kant is even belangrijk. Een productvraag kan ontstaan wanneer iemand antwoordt op een productbericht of “Message Business” kiest op de productdetailpagina. De webhookcontext kan referred_product.catalog_id en referred_product.product_retailer_id bevatten (product-enquiry webhook). Een orderobject kan catalog_id, product_items, aantal, itemprijs, valuta en de product_retailer_id per artikel bevatten (messages object reference). Die velden tonen de selectie. Je eigen systemen bepalen nog steeds wat beloofd kan worden en wat daarna gebeurt.

Maak één operationeel contract van catalogus tot order

Een betrouwbaar proces begint met één geschreven afspraak tussen marketing, klantenservice, commerce-operations en engineering. Daarin staan betekenis en eigenaar van vijf records:

• Klant — wa_id, telefoon of interne contact_uuid: Identiteit en gespreksgeschiedenis verbonden houden
• Catalogus — catalog_id: De productbron van het bericht aanwijzen
• Product — product_retailer_id: Het WhatsApp-item aan een stabiele SKU koppelen
• Interactie — ID van uitgaand bericht en inkomende webhook: Volgorde reconstrueren en events dedupliceren
• Werkitem — aanvraag- of order-ID plus status en eigenaar: Intentie door validatie, herstel en afronding bewegen

Laat één status niet meerdere betekenissen dragen. “Order ontvangen” mag niet tegelijk “betaald”, “gereserveerd” of “verzonden” betekenen. Een bruikbaar minimum is received → validating → reserved → confirmed → fulfilled, met uitgangen als needs_customer, out_of_stock, cancelled en failed. Is een ander commercesysteem eigenaar van betaling of fulfillment, sla dan de referentie daarvan naast het berichtrecord op. Maak WhatsApp niet kunstmatig tot system of record.

Gebruik zeven stappen na de producttik

1. Controleer toelating vóór verzending. Het contact moet het bedoelde bericht mogen ontvangen, het product moet actief zijn, de retailer-ID moet naar precies één actuele SKU verwijzen en het berichttype moet bij de taak passen. Eén product is meestal duidelijker wanneer het gesprek al over één item gaat. Een korte lijst helpt bij een gerichte vergelijking. Een catalogustemplate past alleen bij hernieuwde ontdekking wanneer template en ontvanger daarvoor in aanmerking komen.

2. Leg vast wat is verstuurd. Bewaar klant, catalog_id, iedere product_retailer_id, bericht-ID, taal, zo nodig een prijsopname en broncampagne of workflow. Daarmee kun je later beantwoorden welke prijs de klant zag en waarom dit artikel werd aangeboden.

3. Classificeer het antwoord met context. Een productvraag hoort in de wachtrij te komen met de verwezen catalogus en het product al gekoppeld. Ook een vrij tekstantwoord heeft de context van het bovenliggende bericht nodig wanneer die beschikbaar is. Laat een medewerker niet opnieuw vragen welk product wordt bedoeld als de webhook dat al weet.

4. Valideer vóór een belofte. Zoek de retailer-ID op in het actuele productsysteem. Controleer verkoopbaarheid, prijs, valuta, voorraad of capaciteit, aflever- of afhaalregels en een variant die niet in het bericht zat. Zo wordt een verouderde catalogus een beheersbare uitzondering in plaats van een gebroken belofte.

5. Reserveer en bevestig bewust. Reserveert het bedrijf voorraad, maak de reservering dan in het systeem dat de voorraad bezit en geef haar een vervaltijd. Vertel pas daarna wat wordt vastgehouden, hoe lang en welke actie de aankoop afrondt. Is reserveren niet mogelijk, wees daar expliciet over.

6. Zie een orderwebhook als verzoek tot verwerking. Valideer elk item, aantal, valuta en actueel totaal, dedupliceer de webhook en maak of wijzig daarna de order in het commercesysteem. Stuur afwijkingen naar een exception queue met menselijke eigenaar. De orderpayload bewijst op zichzelf geen betaalafwikkeling of fysieke fulfillment.

7. Sluit de lus. Schrijf de uiteindelijke uitkomst terug naar de gesprekstijdlijn: bevestigd, vervangen, geannuleerd, afgehaald, verzonden of mislukt. Informeer de klant via een toegestane berichtroute, behoud de verantwoordelijke en registreer de reden van vervanging of annulering.

Een realistisch voorbeeld: afhalen bij een tuincentrum

Een klant vraagt naar een rozemarijnplant in een pot van twee liter. Het team stuurt één productbericht waarvan product_retailer_id naar herb-rosemary-2l verwijst. Wanneer de klant reageert, benoemt de enquiry-webhook hetzelfde product. De workflow koppelt het gesprek aan het juiste contact en routeert het naar de afhaalwachtrij.

Vóór iemand afhalen belooft, controleert de voorraaddienst de exacte SKU bij de gevraagde vestiging. Is die beschikbaar, dan maakt het systeem een reservering van 90 minuten en bevestigt de medewerker vestiging, aantal, prijs en vervaltijd. Stuurt de klant een catalogusmandje, dan controleert de orderhandler het artikel opnieuw, dedupliceert de webhook en opent een afhaalwerkitem. Afhalen is pas voltooid wanneer het operationele winkelsysteem de overdracht vastlegt.

Is de catalogus verouderd en de tweeliterpot uitverkocht, dan wisselt de workflow die niet stilzwijgend voor een kleinere pot. Hij zet out_of_stock, stelt pas na controle een concreet alternatief voor en houdt de oorspronkelijke keuze zichtbaar. De waarde is niet méér automatisering, maar een heldere en herstelbare belofte.

Kies het berichttype op besliskosten

Gebruik een single-productbericht wanneer de klant al een product heeft genoemd, een medewerker een specifieke vraag opvolgt of één aanbevolen artikel een duidelijke vervolgstap nodig heeft. Het beperkt vergelijkingswerk en maakt referred-product context eenvoudiger te interpreteren.

Gebruik een multiproductbericht wanneer de klant een kleine set met één betekenisvolle beperking vergelijkt: compatibele onderdelen, drie beschikbare maten of een korte selectie binnen een bekend budget. Maak van iedere sectie geen volledige winkeluitstort. Meer opties vergroten de kans dat prijs, voorraad of eigendom verandert voordat het team reageert.

Gebruik een catalogustemplate wanneer een beleidsconforme template terecht opnieuw productontdekking opent. Na de tik blijven dezelfde ID-koppeling, toelatingscontrole, eigenaar, voorraadvalidatie en uitzonderingsroute nodig. De template verandert het toegangspunt, niet het operationele contract.

Ontwerp foutcontroles vóór de lancering

Het grootste risico is een instabiele product_retailer_id. Behandel die als duurzame integratiesleutel, niet als weergavelabel. Verandert de merchant interne SKU's, gebruik dan een expliciete mapping of migratie; hergebruik een oude ID nooit voor een ander product.

Maak webhookverwerking vervolgens idempotent. Bewaar de event- of bericht-ID zodat herhaalde aflevering veilig is. Onoplosbare producten, ongeldige aantallen, valuta-afwijkingen, ontbrekende contacten en time-outs in vervolgsystemen krijgen benoemde uitzonderingsstatussen. Elke status heeft een wachtrij, eigenaar, reactiedoel en toegestaan klantbericht nodig.

Ontwerp ook voor grenzen van het servicevenster. De huidige ontwikkelaarspagina van DripTell meldt dat productverzending een 422 kan teruggeven wanneer het 24-uursvenster gesloten is (DripTell developer API). Een productieproces heeft daarom een toegestane templateroute of menselijke beslissing nodig, geen blinde retries.

Scheid ten slotte transportsucces van zakelijk succes. Een bezorgd bericht kan geen aanvraag opleveren. Een orderevent kan de voorraadcontrole niet doorstaan. Een bevestigde order kan alsnog niet worden afgehaald. Dashboards en meldingen moeten die verschillen zichtbaar houden.

Meet het pad, niet alleen het berichtvolume

Nuttige meetpunten volgen statusovergangen: productbericht naar aanvraag, tijd tot een benoemde eigenaar, aandeel aanvragen met oplosbare retailer-ID, succes van voorraadvalidatie, reserveringssucces en -verval, orderuitzonderingen per reden, tijd van orderontvangst tot bevestiging en voltooid afhalen of fulfillment. Segmenteer op berichttype, catalogus, productfamilie, taal en workflowbron.

Bepaal geen willekeurige norm vóór een schone nulmeting. Bewijs eerst dat events compleet en gededupliceerd zijn; onderzoek daarna waar gekwalificeerde intentie verloren gaat. Een lager aanvraagpercentage kan acceptabel zijn wanneer een precies productbericht minder maar beter passende vragen oplevert. Een hoog orderaantal is ongezond als vervangingen, annuleringen of ongebruikte reserveringen meegroeien.

Koppel de workflow aan DripTell

DripTell publiceert voor WhatsApp onder meer commercecatalogi, productberichten, een gedeelde inbox, routering, klantcontext, notities en opvolgworkflows (WhatsApp-kanaal). De API-documentatie toont /api/v1/send/product voor één of meer producten met catalog_id, product_retailer_id of products en phone of contact_uuid; orders uit een catalogusmandje staan in de WhatsApp-commercehistorie (developer API).

Dat geeft een praktisch pad: houd de stabiele productsleutel in het bron-commercesysteem, stuur het geschikte bericht, bewaar berichtcontext bij het contact, routeer het antwoord naar de gedeelde inbox en gebruik automatisering alleen voor stappen met expliciete invoer en foutstatussen. Onduidelijke productmatches, voorraadconflicten, prijswijzigingen, vervangingen en fulfillmentproblemen krijgen een menselijke eigenaar.

Lanceer met een bewijsset van tien gevallen

Test vóór brede inzet ten minste: één geldig product; een geldige multiproductsectie; een productvraag; een mandje met aantal twee; een dubbele webhook; een onbekende retailer-ID; verouderde prijs of valuta; uitverkocht na selectie; een gesloten servicevenster; en een time-out van het ordersysteem. Controleer per geval klantbericht, opgeslagen ID's, eigenaar, statusovergang, retrygedrag en eindbewijs van voltooiing.

Het lanceerbesluit hangt af van de vraag of het team elk geval kan uitleggen en herstellen, niet van een fraaie happy flow. Wil je één echt catalogustraject toetsen aan de berichten-, inbox- en automatiseringsgrenzen van DripTell, plan dan een workflowdemo met de SKU-mapping, exception owners en het fulfillmentsysteem in beeld.