WhatsApp Document API: Build the Workflow Around the PDF

Sending a PDF is easy. Running the business process around it is not.

Meta's current document-message documentation shows how the WhatsApp Business Platform sends a document as a media object. In July 2026, Meta also announced that people can open PDFs directly in WhatsApp and make lightweight highlights or annotations on web and desktop (Meta's July 2026 WhatsApp update). Those are useful product improvements, but they do not tell an operations team which version is authoritative, who owns a returned file, or what counts as complete.

That distinction is the heart of a reliable WhatsApp document API workflow: the message transports a file; your operating model moves a case to a verified outcome. This guide builds that model without assuming that a delivered or read message proves the recipient reviewed the document.

1. Separate document transport from document completion

The platform layer answers a narrow question: can a document message be sent to this recipient in the correct conversation context? Meta's documentation provides a document-message request and supports a caption and filename for the file (Meta document messages). Your business layer must answer the rest:

• Is this the correct file for this customer and purpose?
• Is it the current approved version?
• Is the recipient allowed to receive it over this route?
• Who owns questions, corrections, or a returned copy?
• Which event closes the case?
• When should the file and its access path expire?

Treating sent as complete collapses all six questions into one transport event. A better design uses two linked records: a message record for channel delivery and a document case for the business outcome. The message can fail, deliver, or be read. The case can wait for review, need correction, receive a revision, pass validation, or close.

This separation also prevents a common measurement error. A read receipt concerns the WhatsApp message, not proof that the PDF was opened, understood, annotated, signed, or accepted. Only claim the outcome your system can actually observe.

2. Give every document case a stable identity

Before calling an API, create a durable case record. At minimum, it should contain:

• document_case_id — Stable identity for the business process
• contact_id — Recipient identity in your governed customer system
• document_type — Invoice, quotation, renewal, application, evidence request, or another controlled class
• document_version — Immutable version sent in this attempt
• purpose — Why this person should receive the file
• owner_id — Person or queue responsible for the next action
• state — Current business state, independent of message delivery
• source_hash — Integrity check for the exact file, if your security policy uses one
• retention_class — The approved retention and deletion rule
• message_id — Channel message identity returned after sending

Do not reuse a filename as the case identity. renewal.pdf can refer to many customers and versions. A filename is presentation; document_case_id and document_version are control.

A practical state model is: draft, approved_to_send, sent, delivered, waiting_for_customer, revision_received, needs_correction, verified, completed, and expired. You may use fewer states, but each must describe a decision that changes ownership or permitted actions.

3. Run a seven-gate preflight

The send should be the last step in preparation, not the first. Evaluate these gates in order:

1. Purpose: the file and accompanying message match the documented customer request or permitted business purpose.
2. Recipient: the contact and phone number resolve to the intended person; ambiguous matches stop for review.
3. Version: the case points to the approved immutable file, not a mutable “latest” path.
4. Exposure: the media URL and retention design meet your security policy; access is not left public longer than necessary.
5. Presentation: the filename and caption are understandable and contain no accidental internal notes or sensitive identifiers.
6. Conversation rule: the workflow uses the correct free-form or approved-template path for the current WhatsApp service window.
7. Ownership: a named person or queue is ready to handle a question, replacement, or returned document.

The current DripTell API reference exposes POST /api/v1/send/media for an image, video, audio file, document, or sticker from a public HTTPS URL, with an optional caption and a document filename (DripTell developer documentation). The endpoint is useful only after the seven gates pass. A valid request is not the same as a valid business decision.

Store the preflight result with reason codes such as wrong_recipient, unapproved_version, expired_link, window_closed, or no_owner. That makes a non-send explainable and retryable instead of invisible.

4. Make the outbound send idempotent

Document workflows are vulnerable to duplicates. A network timeout can leave the caller unsure whether the file was accepted. An operator may press retry. A scheduler may run twice. If every attempt creates a fresh send, the customer receives multiple copies and cannot tell which one is current.

Create an idempotency key from the case, version, recipient, and intended action—for example, case_482:v3:send_for_review. Before sending, check whether that action already has a successful message identity. If it does, return the existing result. If not, send once and persist the returned message ID beside the exact document version.

Then process delivery status separately. Meta's webhook model carries message status updates and inbound message objects (Meta Cloud API webhook components). Use those events to update transport state, but keep the business state conservative:

• sent means the platform accepted the message attempt;
• delivered means it reached the recipient's device according to the channel event;
• read means the message was marked read, not that the document was reviewed;
• failed means the transport needs a reasoned retry or another approved route.

Never generate a new document version merely because delivery failed. Version changes should reflect content changes, not channel retries.

5. Treat a returned PDF as new evidence

The inbound path deserves as much design as the outbound one. DripTell's current developer reference exposes POST /api/send/media/fetch to retrieve media received from a WhatsApp contact. The requested media must belong to the same workspace as the bearer key, and callers can identify it through a message or media ID (DripTell developer documentation).

When a document arrives:

1. attach the inbound message identity to the open case only when the contact and expected state match;
2. retrieve it through the governed server-side path, never from browser code or a public client secret;
3. validate file type, size, and safety using your organization's approved controls;
4. store it as a new immutable evidence object, not as an overwrite of the sent original;
5. record who or what performed validation and the result;
6. assign the case to the correct reviewer with a due time;
7. acknowledge receipt without promising acceptance before review.

If no open case matches, route the file to a bounded exception queue. Do not guess from a similar filename. A customer may return the wrong attachment, respond from a different number, or send an unrelated document.

6. Preserve revisions instead of replacing history

Meta's July update makes PDF review more convenient on web and desktop, including lightweight highlighting and annotation inside the chat. That can reduce friction, but an annotated copy is still a new object. It should not silently replace the authoritative original.

Use a simple lineage:

source_v3 → sent_copy_v3 → customer_annotation_1 → approved_final_v3

Each arrow represents a documented relationship, not an overwrite. Keep the source version, received file identity, timestamps, validation result, and decision. If the customer merely highlights a question, the case may need clarification rather than approval. If the business issues corrected content, create source_v4 and clearly mark v3 as superseded.

Avoid making WhatsApp the only repository. The conversation is an interaction surface; your governed document system or case record should remain the source of truth for retention, access, and final status.

7. Example: a tenancy renewal pack

Imagine a property manager sending a renewal pack. The case is created with the tenant identity, property reference, approved PDF version, purpose, owner, and response deadline. The system confirms the correct recipient, an allowed conversation route, a controlled media URL, a clear filename, and an available case owner.

After the send, transport events update the message record. The case moves to waiting_for_customer only after the document is delivered; it does not move to completed when the message is read. The tenant returns an annotated PDF with a question about one clause. The received file becomes customer_annotation_1, is routed to the property team's queue, and the case moves to needs_correction or needs_answer.

The team answers the question and, if the content changes, issues a new approved version. When the required business evidence is received and verified under the organization's process, the case closes. This example is an operating pattern, not legal advice or a claim that an annotation constitutes a signature.

The useful feature is explainability. At any point, an operator can answer: which file was sent, to whom, why, what came back, who owns it, and what event is still missing?

8. Measure the funnel you can prove

Build metrics in layers rather than one misleading “PDF conversion rate.”

Transport metrics: send accepted, delivered, read, failed, and failure reason. These describe the channel.

Workflow metrics: time from delivery to first customer response, time from return to assignment, time in exception state, revision count, validation pass rate, and time to verified completion. These describe the operation.

Quality controls: duplicate-send rate, wrong-version incidents, unmatched inbound files, expired-link attempts, cases without an owner, and reopen rate. These reveal system weaknesses.

Do not infer document open or review from message read status. Do not count an inbound attachment as accepted before validation. Define the completion event by document type: payment confirmed, identity evidence verified, quotation approved in the authoritative system, or another explicit outcome.

9. Put the workflow into DripTell

Use DripTell's developer platform for server-side media sends and received-media retrieval, while keeping stable case IDs and version history in your governed workflow. Use the team inbox to route replies, display ownership, keep private notes beside the conversation, and prevent parallel or missing responses. The current inbox also keeps channel identity and delivery state visible with the customer context.

Apply workspace-scoped API keys, least privilege, and your organization's retention controls. DripTell's security overview describes workspace isolation and access controls; your own system still decides which documents may travel over WhatsApp, how public media URLs are protected, and how long evidence is retained.

Start with one document type and one completion event. Map the case states, preflight gates, inbound exception path, and owner before automating the send. Then test a normal return, a wrong version, a duplicate retry, an unmatched file, and an expired case.

If you want to turn an existing PDF exchange into an owned, measurable workflow, book a DripTell demo with one real document type, its approval rule, and the event that should close the case.