WhatsApp Document API: bouw de workflow rond de pdf

Een pdf versturen is eenvoudig. Het bedrijfsproces eromheen betrouwbaar uitvoeren is dat niet.

Meta's actuele documentatie voor documentberichten legt uit hoe het WhatsApp Business Platform een document als mediaobject verstuurt. In juli 2026 kondigde Meta bovendien aan dat mensen pdf's rechtstreeks in WhatsApp kunnen openen en op web en desktop lichte markeringen of annotaties kunnen toevoegen (Meta's WhatsApp-update van juli 2026). Dat zijn nuttige productverbeteringen, maar ze bepalen niet welke versie leidend is, wie een teruggestuurd bestand beheert of wanneer het proces klaar is.

Daar draait een betrouwbare workflow met de WhatsApp document API om: het bericht vervoert een bestand; jouw operationele model brengt een dossier naar een geverifieerde uitkomst. Deze handleiding bouwt dat model zonder aan te nemen dat een bezorgd of gelezen bericht bewijst dat de ontvanger het document heeft beoordeeld.

1. Scheid documenttransport van dossierafhandeling

De platformlaag beantwoordt een smalle vraag: kan een documentbericht in de juiste gesprekscontext naar deze ontvanger worden gestuurd? Meta documenteert het verzoek en ondersteunt een bijschrift en bestandsnaam (documentberichten van Meta). De bedrijfslaag moet de overige vragen beantwoorden:

• Is dit het juiste bestand voor deze klant en dit doel?
• Is dit de huidige goedgekeurde versie?
• Mag deze ontvanger het langs deze route ontvangen?
• Wie behandelt vragen, correcties of een retourbestand?
• Welke gebeurtenis sluit het dossier?
• Wanneer vervallen het bestand en het toegangspad?

Wie sent gelijkstelt aan complete, reduceert alle zes vragen tot één transportgebeurtenis. Een beter ontwerp gebruikt twee gekoppelde registraties: een berichtrecord voor kanaalbezorging en een documentdossier voor het bedrijfsresultaat. Het bericht kan mislukken, worden bezorgd of gelezen. Het dossier kan wachten op beoordeling, een correctie nodig hebben, een revisie ontvangen, worden gevalideerd of sluiten.

Deze scheiding voorkomt ook een veelgemaakte meetfout. Een leesbevestiging gaat over het WhatsApp-bericht en bewijst niet dat de pdf is geopend, begrepen, geannoteerd, ondertekend of geaccepteerd. Claim alleen de uitkomst die je systeem echt kan waarnemen.

2. Geef elk documentdossier een stabiele identiteit

Maak vóór de API-aanroep een duurzaam dossierrecord. Minimaal bevat het:

• document_case_id — Stabiele identiteit van het bedrijfsproces
• contact_id — Ontvanger in het beheerde klantensysteem
• document_type — Factuur, offerte, verlenging, aanvraag of andere beheerste klasse
• document_version — Onveranderlijke versie van deze verzendpoging
• purpose — Waarom deze persoon het bestand hoort te ontvangen
• owner_id — Persoon of wachtrij verantwoordelijk voor de volgende actie
• state — Huidige bedrijfsstatus, los van berichtbezorging
• source_hash — Integriteitscontrole voor het exacte bestand, als het beveiligingsbeleid die gebruikt
• retention_class — Goedgekeurde bewaar- en verwijderregel
• message_id — Kanaalidentiteit die na verzending wordt teruggegeven

Gebruik de bestandsnaam niet als dossieridentiteit. renewal.pdf kan bij veel klanten en versies horen. De bestandsnaam is presentatie; document_case_id en document_version zijn beheersing.

Een bruikbaar statusmodel is: draft, approved_to_send, sent, delivered, waiting_for_customer, revision_received, needs_correction, verified, completed en expired. Je kunt met minder statussen werken, maar elke status moet een beslissing beschrijven die de eigenaar of toegestane actie verandert.

3. Voer een preflight met zeven poorten uit

Verzenden is de laatste voorbereidingsstap, niet de eerste. Beoordeel de poorten in deze volgorde:

1. Doel: bestand en begeleidend bericht passen bij het vastgelegde klantverzoek of toegestane bedrijfsdoel.
2. Ontvanger: contact en telefoonnummer verwijzen ondubbelzinnig naar de bedoelde persoon; twijfel gaat naar beoordeling.
3. Versie: het dossier verwijst naar het goedgekeurde onveranderlijke bestand, niet naar een wijzigbaar “latest”-pad.
4. Blootstelling: media-URL en bewaartermijn voldoen aan het beveiligingsbeleid; openbare toegang blijft niet langer bestaan dan nodig.
5. Presentatie: bestandsnaam en bijschrift zijn duidelijk en bevatten geen interne notities of gevoelige identifiers.
6. Gespreksregel: de workflow kiest de juiste vrije of goedgekeurde template-route voor het huidige WhatsApp-servicevenster.
7. Eigenaarschap: een genoemde persoon of wachtrij staat klaar voor vragen, vervanging of een teruggestuurd document.

De huidige DripTell-API biedt POST /api/v1/send/media voor een afbeelding, video, audiobestand, document of sticker via een openbare HTTPS-URL, met een optioneel bijschrift en een documentnaam (DripTell-documentatie voor ontwikkelaars). Het endpoint is pas nuttig nadat alle zeven poorten zijn gepasseerd. Een geldig verzoek is niet automatisch een geldige bedrijfsbeslissing.

Sla de uitkomst op met reden-codes als wrong_recipient, unapproved_version, expired_link, window_closed en no_owner. Zo blijft een niet-verzonden actie verklaarbaar en veilig opnieuw uitvoerbaar.

4. Maak de uitgaande verzending idempotent

Documentworkflows zijn gevoelig voor duplicaten. Bij een netwerktime-out weet de aanroeper mogelijk niet of het bestand is aangenomen. Een medewerker kan opnieuw klikken en een planner kan tweemaal draaien. Als elke poging een nieuw bericht maakt, ontvangt de klant meerdere exemplaren en is onduidelijk welke actueel is.

Maak een idempotentiesleutel uit dossier, versie, ontvanger en bedoelde actie, bijvoorbeeld case_482:v3:send_for_review. Controleer vóór verzending of die actie al een succesvolle berichtidentiteit heeft. Zo ja, geef het bestaande resultaat terug. Zo nee, stuur één keer en leg de bericht-ID naast de exacte documentversie vast.

Verwerk bezorgstatus daarna apart. Meta's webhookmodel bevat statusupdates en objecten van inkomende berichten (webhookcomponenten van Meta Cloud API). Gebruik die gebeurtenissen voor de transportstatus, maar houd de bedrijfsstatus terughoudend:

• sent betekent dat het platform de poging heeft geaccepteerd;
• delivered betekent dat het bericht volgens het kanaalevent het toestel heeft bereikt;
• read betekent dat het bericht als gelezen is gemarkeerd, niet dat het document is beoordeeld;
• failed betekent dat een beredeneerde herhaling of andere goedgekeurde route nodig is.

Maak geen nieuwe documentversie alleen omdat bezorging faalde. Versies horen inhoudswijzigingen te weerspiegelen, geen kanaalherhalingen.

5. Behandel een teruggestuurde pdf als nieuw bewijs

Het inkomende pad verdient evenveel ontwerp. De huidige DripTell-referentie biedt POST /api/send/media/fetch om media te verkrijgen die een WhatsApp-contact heeft gestuurd. De media moeten bij dezelfde workspace als de bearer-sleutel horen en kunnen met een bericht- of media-ID worden aangeduid (DripTell-documentatie voor ontwikkelaars).

Wanneer een document binnenkomt:

1. koppel de inkomende bericht-ID alleen aan een open dossier als contact en verwachte status overeenkomen;
2. haal het via een beheerd serverpad op, nooit via browsercode of een geheim in een publieke client;
3. valideer bestandstype, grootte en veiligheid met de goedgekeurde controles van je organisatie;
4. bewaar het als een nieuw, onveranderlijk bewijsobject en overschrijf het verzonden origineel niet;
5. registreer wie of welk systeem valideerde en met welk resultaat;
6. wijs het dossier met een deadline toe aan de juiste beoordelaar;
7. bevestig ontvangst zonder acceptatie te beloven vóór beoordeling.

Past geen open dossier, stuur het bestand dan naar een begrensde uitzonderingswachtrij. Gok niet op basis van een vergelijkbare naam. Een klant kan het verkeerde bestand terugsturen, vanaf een ander nummer reageren of iets ongerelateerds bijvoegen.

6. Bewaar revisies in plaats van de geschiedenis te vervangen

Meta's update van juli maakt pdf-beoordeling op web en desktop eenvoudiger, inclusief lichte markeringen en annotaties in de chat. Dat kan frictie verminderen, maar een geannoteerde kopie is nog steeds een nieuw object en mag het gezaghebbende origineel niet stilzwijgend vervangen.

Gebruik een eenvoudige afstamming:

source_v3 → sent_copy_v3 → customer_annotation_1 → approved_final_v3

Elke pijl is een vastgelegde relatie, geen overschrijving. Bewaar bronversie, ontvangen bestands-ID, tijdstippen, validatieresultaat en besluit. Markeert de klant alleen een vraag, dan is verduidelijking nodig en nog geen goedkeuring. Wijzigt het bedrijf de inhoud, maak dan source_v4 en markeer v3 duidelijk als vervangen.

Maak WhatsApp niet het enige archief. Het gesprek is een interactieoppervlak; je beheerde documentensysteem of dossierrecord blijft de bron van waarheid voor toegang, bewaring en eindstatus.

7. Voorbeeld: een huurverlengingspakket

Stel dat een vastgoedbeheerder een verlengingspakket verstuurt. Het dossier bevat de huurder, het object, de goedgekeurde pdf-versie, het doel, de eigenaar en de reactiedatum. Het systeem bevestigt ontvanger, toegestane gespreksroute, beheerste media-URL, duidelijke bestandsnaam en beschikbare eigenaar.

Na verzending actualiseren transportevents het berichtrecord. Het dossier gaat pas na bezorging naar waiting_for_customer en niet bij een leesbevestiging naar completed. De huurder stuurt een geannoteerde pdf terug met een vraag over een clausule. Het bestand wordt customer_annotation_1, gaat naar de vastgoedwachtrij en het dossier naar needs_correction of needs_answer.

Het team beantwoordt de vraag en geeft, als de inhoud verandert, een nieuwe goedgekeurde versie uit. Het dossier sluit wanneer het vereiste bedrijfsbewijs binnen de eigen procedure is ontvangen en geverifieerd. Dit is een operationeel patroon, geen juridisch advies en geen bewering dat een annotatie een handtekening vormt.

De waarde is verklaarbaarheid. Een medewerker kan steeds zeggen welk bestand naar wie is gestuurd, waarom, wat terugkwam, wie eigenaar is en welke gebeurtenis nog ontbreekt.

8. Meet de funnel die je kunt bewijzen

Bouw statistieken in lagen in plaats van één misleidend “pdf-conversiepercentage”.

Transportstatistieken: verzending geaccepteerd, bezorgd, gelezen, mislukt en faalreden. Die beschrijven het kanaal.

Workflowstatistieken: tijd van bezorging tot eerste reactie, van retour tot toewijzing, tijd in uitzonderingsstatus, aantal revisies, validatiesucces en tijd tot geverifieerde voltooiing. Die beschrijven de operatie.

Kwaliteitscontroles: dubbele verzendingen, incidenten met verkeerde versies, ongekoppelde inkomende bestanden, pogingen via verlopen links, dossiers zonder eigenaar en heropeningen. Die tonen systeemzwakte.

Leid het openen of beoordelen van een document niet af uit de leesstatus van het bericht. Tel een bijlage niet als geaccepteerd vóór validatie. Definieer voltooiing per documenttype: bevestigde betaling, geverifieerd identiteitsbewijs, goedgekeurde offerte in het bronsysteem of een andere expliciete uitkomst.

9. Breng de workflow onder in DripTell

Gebruik het DripTell-ontwikkelaarsplatform voor server-side mediaverzending en het ophalen van ontvangen bestanden, terwijl stabiele dossier-ID's en versiegeschiedenis in je beheerde workflow blijven. Gebruik de gedeelde teaminbox om reacties te routeren, eigenaarschap te tonen, interne notities bij het gesprek te bewaren en dubbele of ontbrekende antwoorden te voorkomen. De inbox houdt kanaalidentiteit en bezorgstatus zichtbaar bij de klantcontext.

Pas workspace-gebonden API-sleutels, minimale rechten en je eigen bewaarregels toe. Het beveiligingsoverzicht van DripTell beschrijft workspace-isolatie en toegangscontrole; je systeem blijft bepalen welke documenten via WhatsApp mogen reizen, hoe openbare media-URL's worden beschermd en hoe lang bewijs blijft bestaan.

Begin met één documenttype en één voltooiingsgebeurtenis. Leg statussen, preflightpoorten, uitzonderingspad en eigenaar vast vóór je verzending automatiseert. Test daarna een normale retour, verkeerde versie, dubbele poging, ongekoppeld bestand en verlopen dossier.

Wil je een bestaande pdf-uitwisseling omzetten in een toegewezen en meetbare workflow, boek dan een DripTell-demo met één echt documenttype, de goedkeuringsregel en de gebeurtenis die het dossier moet sluiten.