Photos, Voice Notes and PDFs: Handling WhatsApp Media in a CRM Pipeline

#whatsapp #crm #automation #webdev

Text messages are the easy part of a WhatsApp-to-CRM integration. Real customers send photos of products, voice notes, screenshots of payments and PDFs of floor plans. If your pipeline drops them, your sales team works blind. Here is a pattern for WhatsApp CRM automation for photos and voice notes that keeps media useful without filling your CRM with blobs.

Disclosure: I run NxFlowAI, an automation agency. The pattern is provider-neutral.

1. Treat media as a separate, async job

Webhook handlers should acknowledge fast. Do not download media inside the handler.

def on_webhook(event):
    msg = event["message"]
    record_message(msg)                    # text + metadata, idempotent on message id
    if msg.get("media_id"):
        enqueue("fetch_media", {"message_id": msg["id"], "media_id": msg["media_id"]})
    return 200

2. Fetch, store, link

Provider media links are usually temporary and need authentication. Fetch the file once, store it in storage you control, and put a link (not the file) on the CRM record.

def fetch_media(job):
    blob, mime = provider.download(job["media_id"])     # auth with your provider token
    key = f"wa-media/{job['message_id']}.{ext(mime)}"
    storage.put(key, blob, private=True)
    crm.add_note(contact_for(job["message_id"]),
                 text=f"WhatsApp {mime} received", link=signed_url(key))

3. Decide per media type

Type	Default handling
Image	Store + link; optional AI caption for search
Voice note	Store + link; optional transcript as a CRM note, flagged "machine transcript"
PDF / document	Store + link; never auto-parse payment or ID documents without a person
Screenshot of payment	Store + link; route to a person, never auto-confirm

4. Set retention on purpose

Decide how long media is kept and who can see it. Customer photos and documents can be personal data; keep access narrow and delete on a schedule your business agrees with.

5. Test with real-world mess

Include in your test set: a voice note in a second language, a blurry photo, a multi-page PDF, a forwarded image, and a media message with no caption.

6. Monitor

Alert on failed fetches and on media that never got linked to a contact.

Media handling is one of the items we map during a 72-hour audit before building. For the wider decision of custom versus packaged tools, see our custom AI vs off-the-shelf chatbots comparison.

DEV Community