API de documentos de WhatsApp: construye el flujo alrededor del PDF

Enviar un PDF es sencillo. Operar de forma fiable el proceso de negocio que lo rodea no lo es.

La documentación actual de Meta sobre mensajes de documento explica cómo WhatsApp Business Platform envía un documento como objeto multimedia. En julio de 2026, Meta también anunció que las personas pueden abrir PDF directamente en WhatsApp y hacer resaltados o anotaciones ligeras en la web y la aplicación de escritorio (actualización de WhatsApp de Meta de julio de 2026). Son mejoras útiles, pero no indican qué versión es la oficial, quién se hace cargo de un archivo devuelto ni qué significa que el proceso haya terminado.

Esa es la esencia de un flujo fiable con la WhatsApp document API: el mensaje transporta un archivo; el modelo operativo lleva un caso hasta un resultado verificado. Esta guía construye ese modelo sin asumir que un mensaje entregado o leído demuestra que el destinatario revisó el documento.

1. Separa el transporte del documento de la finalización del caso

La capa de plataforma responde a una pregunta limitada: ¿puede enviarse un mensaje de documento a este destinatario en el contexto correcto de la conversación? Meta documenta la solicitud y admite un pie y un nombre de archivo (mensajes de documento de Meta). La capa de negocio debe responder el resto:

• ¿Es el archivo correcto para este cliente y propósito?
• ¿Es la versión vigente y aprobada?
• ¿Puede este destinatario recibirlo por esta vía?
• ¿Quién se ocupa de preguntas, correcciones o una copia devuelta?
• ¿Qué evento cierra el caso?
• ¿Cuándo deben caducar el archivo y su ruta de acceso?

Tratar sent como complete reduce las seis preguntas a un evento de transporte. Un diseño mejor usa dos registros vinculados: un registro de mensaje para la entrega del canal y un caso de documento para el resultado de negocio. El mensaje puede fallar, entregarse o leerse. El caso puede esperar revisión, requerir una corrección, recibir una versión, superar la validación o cerrarse.

Esta separación también evita un error frecuente de medición. Un recibo de lectura se refiere al mensaje de WhatsApp; no demuestra que el PDF se abriera, comprendiera, anotara, firmara o aceptara. Registra solo el resultado que el sistema pueda observar de verdad.

2. Asigna una identidad estable a cada caso

Antes de llamar a la API, crea un registro duradero. Como mínimo debe incluir:

• document_case_id — Identidad estable del proceso de negocio
• contact_id — Identidad del destinatario en el sistema de clientes gobernado
• document_type — Factura, presupuesto, renovación, solicitud u otra clase controlada
• document_version — Versión inmutable enviada en este intento
• purpose — Motivo por el que esta persona debe recibir el archivo
• owner_id — Persona o cola responsable de la siguiente acción
• state — Estado de negocio actual, independiente de la entrega
• source_hash — Comprobación de integridad del archivo exacto, si la política de seguridad la utiliza
• retention_class — Regla aprobada de conservación y borrado
• message_id — Identidad del mensaje devuelta tras el envío

No uses el nombre del archivo como identidad del caso. renewal.pdf puede pertenecer a muchos clientes y versiones. El nombre es presentación; document_case_id y document_version son control.

Un modelo práctico de estados es: draft, approved_to_send, sent, delivered, waiting_for_customer, revision_received, needs_correction, verified, completed y expired. Puedes usar menos, pero cada estado debe describir una decisión que cambie el responsable o las acciones permitidas.

3. Ejecuta una comprobación previa de siete puertas

El envío debe ser el último paso de la preparación. Evalúa estas puertas en orden:

1. Propósito: el archivo y el mensaje corresponden a la solicitud documentada del cliente o al fin empresarial permitido.
2. Destinatario: el contacto y el teléfono resuelven a la persona prevista; cualquier ambigüedad se detiene para revisión.
3. Versión: el caso apunta al archivo aprobado e inmutable, no a una ruta “latest” que pueda cambiar.
4. Exposición: la URL multimedia y la retención cumplen la política de seguridad; el acceso público no permanece más de lo necesario.
5. Presentación: el nombre y el pie son comprensibles y no incluyen notas internas ni identificadores sensibles por accidente.
6. Regla de conversación: el flujo usa la vía libre o la plantilla aprobada correcta para la ventana de servicio vigente de WhatsApp.
7. Responsabilidad: una persona o cola concreta está preparada para atender una pregunta, sustitución o documento devuelto.

La referencia actual de DripTell ofrece POST /api/v1/send/media para enviar una imagen, vídeo, audio, documento o sticker desde una URL HTTPS pública, con pie opcional y nombre de documento (documentación para desarrolladores de DripTell). El endpoint solo resulta útil después de superar las siete puertas. Una solicitud válida no equivale a una decisión empresarial válida.

Guarda el resultado con códigos como wrong_recipient, unapproved_version, expired_link, window_closed o no_owner. Así, un no envío es explicable y reintentable, no invisible.

4. Haz idempotente el envío saliente

Los flujos de documentos son vulnerables a los duplicados. Un timeout puede dejar al sistema sin saber si el archivo fue aceptado. Un agente puede pulsar de nuevo y un programador puede ejecutarse dos veces. Si cada intento crea un envío, el cliente recibe varias copias y no sabe cuál es la actual.

Crea una clave de idempotencia con el caso, la versión, el destinatario y la acción prevista; por ejemplo, case_482:v3:send_for_review. Antes de enviar, comprueba si esa acción ya tiene una identidad de mensaje exitosa. Si la tiene, devuelve el resultado existente. Si no, envía una vez y guarda el ID junto a la versión exacta.

Procesa el estado de entrega por separado. El modelo de webhook de Meta contiene actualizaciones de estado y objetos de mensajes entrantes (componentes de webhook de Meta Cloud API). Usa esos eventos para el transporte, pero conserva prudente el estado de negocio:

• sent significa que la plataforma aceptó el intento;
• delivered significa que alcanzó el dispositivo según el evento del canal;
• read significa que el mensaje se marcó como leído, no que el documento se revisó;
• failed indica que hace falta un reintento razonado u otra vía aprobada.

No generes una nueva versión porque fallara la entrega. Una versión debe reflejar cambios de contenido, no reintentos del canal.

5. Trata el PDF devuelto como nueva evidencia

La entrada merece tanto diseño como la salida. La referencia actual de DripTell ofrece POST /api/send/media/fetch para recuperar archivos recibidos de un contacto de WhatsApp. El archivo debe pertenecer al mismo workspace que la clave bearer y puede identificarse por el ID de mensaje o de media (documentación para desarrolladores de DripTell).

Cuando llega un documento:

1. vincula el ID entrante a un caso abierto solo si coinciden el contacto y el estado esperado;
2. recupéralo por una vía de servidor gobernada, nunca desde código del navegador ni con un secreto en un cliente público;
3. valida tipo, tamaño y seguridad con los controles aprobados por tu organización;
4. guárdalo como un objeto de evidencia nuevo e inmutable, sin sobrescribir el original enviado;
5. registra quién o qué sistema validó y el resultado;
6. asigna el caso al revisor correcto con un plazo;
7. confirma la recepción sin prometer aceptación antes de revisar.

Si no coincide con ningún caso, envíalo a una cola de excepciones acotada. No adivines por un nombre parecido. El cliente puede haber devuelto otro adjunto, respondido desde otro número o enviado un documento ajeno.

6. Conserva las revisiones en lugar de reemplazar el historial

La actualización de Meta de julio facilita revisar PDF en web y escritorio, con resaltados y anotaciones ligeras en el chat. Puede reducir fricción, pero una copia anotada sigue siendo un objeto nuevo y no debe sustituir silenciosamente al original oficial.

Usa un linaje simple:

source_v3 → sent_copy_v3 → customer_annotation_1 → approved_final_v3

Cada flecha representa una relación documentada, no una sobrescritura. Conserva la versión fuente, la identidad recibida, los tiempos, el resultado de validación y la decisión. Si el cliente solo resalta una pregunta, el caso puede necesitar aclaración y no aprobación. Si la empresa corrige el contenido, crea source_v4 y marca claramente v3 como sustituida.

No conviertas WhatsApp en el único repositorio. La conversación es la superficie de interacción; el sistema documental gobernado o el registro del caso debe seguir siendo la fuente de verdad para acceso, retención y estado final.

7. Ejemplo: un paquete de renovación de alquiler

Imagina que un administrador inmobiliario envía un paquete de renovación. El caso se crea con el inquilino, la propiedad, la versión aprobada del PDF, el propósito, el responsable y la fecha de respuesta. El sistema confirma destinatario, vía permitida, URL controlada, nombre claro y responsable disponible.

Tras el envío, los eventos actualizan el mensaje. El caso pasa a waiting_for_customer al entregarse, pero no a completed al leerse. El inquilino devuelve un PDF anotado con una duda sobre una cláusula. El archivo se convierte en customer_annotation_1, va a la cola del equipo y el caso cambia a needs_correction o needs_answer.

El equipo responde y, si cambia el contenido, emite una nueva versión aprobada. El caso se cierra cuando la evidencia empresarial requerida se recibe y verifica conforme al proceso de la organización. Es un patrón operativo, no asesoramiento jurídico ni una afirmación de que una anotación sea una firma.

La ventaja es la explicabilidad. En cualquier momento se puede responder qué archivo se envió, a quién, por qué, qué volvió, quién es responsable y qué evento falta.

8. Mide el embudo que puedas demostrar

Construye métricas por capas en vez de un engañoso “porcentaje de conversión del PDF”.

Métricas de transporte: envío aceptado, entregado, leído, fallido y causa. Describen el canal.

Métricas de flujo: tiempo de entrega a primera respuesta, de devolución a asignación, tiempo en excepción, número de revisiones, tasa de validación y tiempo hasta el cierre verificado. Describen la operación.

Controles de calidad: duplicados, incidencias de versión incorrecta, archivos entrantes sin caso, intentos con enlace caducado, casos sin responsable y reaperturas. Revelan debilidades.

No infieras apertura o revisión del estado de lectura. No cuentes un adjunto como aceptado antes de validarlo. Define el cierre por tipo: pago confirmado, prueba de identidad verificada, presupuesto aprobado en el sistema de referencia u otro resultado explícito.

9. Lleva el flujo a DripTell

Usa la plataforma para desarrolladores de DripTell para enviar medios desde el servidor y recuperar archivos recibidos, mientras mantienes los ID estables y el historial de versiones en tu flujo gobernado. Usa la bandeja compartida del equipo para dirigir respuestas, mostrar responsabilidad, mantener notas privadas junto a la conversación y evitar respuestas paralelas o ausentes. La bandeja conserva la identidad del canal y el estado de entrega con el contexto del cliente.

Aplica claves API limitadas al workspace, mínimo privilegio y las reglas de retención de tu organización. El resumen de seguridad de DripTell describe aislamiento y controles de acceso; tu sistema sigue decidiendo qué documentos pueden viajar por WhatsApp, cómo proteger las URL públicas y cuánto conservar la evidencia.

Empieza con un tipo de documento y un evento de cierre. Define estados, puertas previas, ruta de excepciones y responsable antes de automatizar el envío. Después prueba una devolución normal, una versión equivocada, un reintento duplicado, un archivo sin coincidencia y un caso caducado.

Si quieres convertir un intercambio de PDF existente en un flujo asignado y medible, reserva una demo de DripTell con un tipo real, su regla de aprobación y el evento que debe cerrar el caso.