Skip to main content
Utilice estas prácticas para enviar mensajes de WhatsApp de forma fiable a escala de producción. Elegirá el endpoint adecuado, correlacionará cada intento, convergerá el estado de entrega, reintentará de forma segura, aplicará el consentimiento y controlará el rendimiento.

​
Antes de comenzar

  • Conecte y registre los números de teléfono comerciales de WhatsApp que enviarán los mensajes.
  • Guarde su clave de API de YCloud en el servidor.
  • Configure un endpoint de webhook firmado para whatsapp.message.updated.
  • Defina cómo registra su sistema el consentimiento, las cancelaciones de suscripción, el propósito del mensaje y la retención.
  • Asigne responsables para el envío, el procesamiento de webhooks y la respuesta a incidentes.

​
Elija el endpoint de envío

Utilice el endpoint en cola por defecto. Utilice el envío directo únicamente cuando la aplicación deba saber si WhatsApp aceptó el envío antes de continuar. Una respuesta correcta de cualquiera de los dos endpoints no constituye una prueba de entrega. Almacene el id del mensaje devuelto y utilice los eventos whatsapp.message.updated para saber si el mensaje está sent, failed, delivered o read.
No cambie toda una carga de trabajo de gran volumen a sendDirectly para reducir la latencia de la cola. Las llamadas síncronas retienen recursos de la aplicación y aun así requieren gestión asíncrona del estado.

​
Cree un único registro de envío interno

Cree un registro duradero antes de llamar a la API. Asigne al registro una clave de negocio única, como el ID del evento de pedido más el propósito del mensaje. Haga cumplir esa unicidad en su base de datos para que los procesos simultáneos no puedan enviar el mismo evento de negocio dos veces. Registre al menos: Utilice un externalId opaco que no contenga contenido del mensaje ni datos personales. La API recomienda un valor único, pero externalId es un campo de referencia. No es una clave de idempotencia del lado del servidor y no hace que las solicitudes POST repetidas sean seguras.

​
Conecte la respuesta con los webhooks de estado

El siguiente ejemplo utiliza los mismos identificadores a lo largo del flujo de trabajo de envío.

​
1. Enviar el mensaje

​
2. Almacenar la respuesta aceptada

Guarde MESSAGE_ID, accepted y el tiempo de respuesta en el registro interno existente. No marque la notificación de negocio como entregada.

​
3. Aplicar eventos de estado posteriores

Coteje el evento mediante whatsappMessage.id. Utilice externalId para la conciliación de negocio y wamid para la investigación del lado del proveedor.

​
Construya un modelo de estado convergente

La progresión habitual es accepted → sent → delivered → read. failed puede ocurrir antes o después de una actualización de sent. Los webhooks pueden duplicarse, retrasarse o entregarse desordenados. Una actualización de read también puede llegar sin un evento delivered independiente. Procese cada evento de la siguiente manera:
  1. Verifique la firma del webhook con respecto al cuerpo sin procesar de la solicitud.
  2. Almacene de forma duradera el evento, utilizando el id del evento como clave de deduplicación.
  3. Devuelva una respuesta 2xx de inmediato y, a continuación, procese el evento de forma asíncrona.
  4. Coteje whatsappMessage.id con el registro de envío interno.
  5. Guarde el estado del evento y sus marcas de tiempo de mensaje disponibles. Conserve los metadatos sin procesar del evento necesarios para una auditoría, pero elimine el contenido innecesario del mensaje.
  6. Actualice la vista de negocio actual sin descartar información contradictoria o posterior. Considere read como prueba de que la entrega se produjo, incluso cuando no exista el evento delivered independiente.
  7. Recupere GET /whatsapp/messages/{id} cuando los eventos entren en conflicto, falte un estado final más allá de su objetivo de servicio o la canalización de webhooks no haya estado disponible.
No implementes el modelo de estado como una regla que solo acepte un estado de mayor rango. Las actualizaciones reales de entrega no siempre llegan en ese orden. Conserva un historial de eventos y haz que la conciliación sea capaz de corregir la vista actual.

​
Reintentar sin crear envíos duplicados

Clasifica el fallo antes de reintentar. Una política segura para la aplicación puede comenzar con un número reducido de intentos, retrasos exponenciales, jitter completo y un tiempo transcurrido máximo. Estos son controles de la aplicación, no garantías de la API. Envía los intentos agotados a una cola de revisión en lugar de reintentar indefinidamente. Antes de cada reintento:
  • Bloquea o reclama atómicamente la clave interna de negocio.
  • Comprueba si el registro ya cuenta con un id de YCloud o un evento de estado.
  • No utilices un nuevo externalId para ocultar un intento ambiguo anterior.
  • Detén el proceso tras alcanzar el límite configurado de intentos o de antigüedad.
  • Requiere una acción deliberada por parte de un operador antes de volver a ejecutar un envío ambiguo.

​
Elegir plantillas y mensajes de sesión

Utiliza una plantilla aprobada cuando inicies un mensaje comercial o envíes fuera de la ventana de servicio al cliente de 24 horas. Selecciona la categoría de la plantilla en función del motivo por el que el usuario recibe el mensaje y mantén su nombre, idioma y contrato de variables en la configuración de la aplicación. Utiliza mensajes de texto, multimedia, interactivos, de ubicación, de contacto o de reacción solo cuando la ventana de servicio al cliente esté abierta y se permita ese tipo de contenido. Determina la ventana a partir del mensaje más reciente del cliente. No deduzcas que la ventana está abierta a partir de tu último mensaje saliente. Consulta Administrar plantillas de WhatsApp para conocer las versiones de plantillas, puertas de aprobación, configuraciones regionales y reversión.

​
Gestionar archivos multimedia de forma eficiente

  • Valida el tipo MIME admitido y el tamaño del archivo antes de subirlo. No reintentes un archivo excesivamente grande o incompatible sin haberlo modificado.
  • Sube el archivo con el número de teléfono comercial que enviará el mensaje.
  • Reutiliza el ID multimedia devuelto para envíos repetidos del mismo recurso aprobado mientras siga siendo válido. El contenido multimedia subido se conserva durante 30 días.
  • Almacena la suma de verificación (checksum) del recurso, el tipo MIME, el ID multimedia, el remitente y la hora de vencimiento para que los workers no suban el mismo archivo para cada destinatario.
  • Vuelve a subirlo después del vencimiento o cuando cambie el contexto del remitente.
  • Utiliza una URL pública en su lugar cuando el esquema del mensaje requiera un enlace, incluyendo el contenido multimedia en los encabezados de mensajes interactivos.
  • Transmite subidas grandes desde el almacenamiento mediante streaming, establece tiempos de espera de solicitud y elimina los archivos temporales locales tras su uso.

​
Exigir el consentimiento y minimizar los datos

Registra la fuente del consentimiento, el propósito, la hora y el canal permitido antes del envío. Aplica la opción de exclusión (opt-out) válida más reciente en campañas, flujos de trabajo transaccionales donde la política lo requiera, reintentos y reejecuciones manuales. Para POST /whatsapp/messages, establece filterUnsubscribed: true y filterBlocked: true cuando el flujo de trabajo deba aplicar las listas de supresión de YCloud. Estos campos tienen como valor predeterminado false. No se aplican a sendDirectly, por lo que un flujo de trabajo de envío directo debe comprobar la supresión antes de realizar la llamada a la API. Los filtros de supresión son una comprobación de seguridad final, no un sustituto del consentimiento. Almacena únicamente los identificadores y los metadatos de entrega necesarios para el fin indicado. Excluye claves de API, variables de plantilla, cuerpos de mensajes y números de teléfono de los registros generales de la aplicación. Aplica controles de retención y acceso a los registros de mensajes y webhooks.

​
Controlar el rendimiento de los lotes

Coloca el trabajo por lotes en una cola acotada y envíalo mediante un grupo fijo de workers. Realiza un seguimiento de la concurrencia por separado por cuenta y número de teléfono comercial para que un único remitente o tenant no pueda consumir todos los workers. Aplica contrapresión cuando aumente cualquiera de estas señales:
  • respuestas 429
  • latencia de solicitudes y tiempos de espera agotados
  • respuestas 5xx
  • antigüedad de la cola o acumulación de reintentos
  • retraso de webhooks y mensajes accepted no resueltos
Reduce la concurrencia cuando YCloud o la entrega descendente se ralenticen. Reanuda gradualmente tras la recuperación. No reintentes los mensajes fallidos a una velocidad mayor que la tasa de envío original. Monitorea al menos el volumen de solicitudes, la tasa de aceptación, la tasa de errores por estado HTTP y código de error, la tasa de estado de entrega, el tiempo transcurrido desde accepted hasta cada estado posterior, la profundidad de la cola, la antigüedad del elemento más antiguo de la cola, el recuento de reintentos, el retraso del webhook, el recuento de desduplicaciones y la desviación de conciliación. Genera alertas ante cambios sostenidos respecto a tu línea base habitual, no ante un único mensaje fallido.

​
Antipatrones comunes

  • Marcar un mensaje como entregado cuando la API devuelve accepted.
  • Tratar externalId como una clave de idempotencia de YCloud.
  • Reintentar cada respuesta distinta de 2xx o tiempo de espera agotado sin un límite de intentos.
  • Usar sendDirectly para todo el tráfico.
  • Asumir que los webhooks son únicos, ordenados o completos.
  • Enviar mensajes de formato libre fuera de la ventana de atención al cliente.
  • Subir el mismo archivo multimedia para cada destinatario.
  • Depender de filtros de supresión sin registrar el consentimiento.
  • Registrar claves de API en los logs, cargas útiles completas o datos personales innecesarios.
  • Iniciar un lote con concurrencia sin límites y sin contrapresión.

​
Lista de verificación para la puesta en producción

  • La elección del endpoint se ajusta a la carga de trabajo y al requisito de latencia.
  • Una regla de unicidad en la base de datos protege la clave de negocio interna.
  • externalId, el id de YCloud y wamid tienen funciones documentadas y diferenciadas.
  • Las respuestas iniciales permanecen como no definitivas hasta que llegue la confirmación de estado.
  • Se han probado las firmas de webhooks, la deduplicación de eventos, el acuse de recibo rápido y la retransmisión.
  • Una tarea programada de recuperación concilia los eventos retrasados o faltantes.
  • Los fallos reintentables y no reintentables tienen rutas de gestión delimitadas.
  • Las reglas de plantillas y ventanas de sesión se aplican antes del envío.
  • Las subidas de archivos multimedia se validan, reutilizan, expiran y limpian de forma segura.
  • Se verifican los controles de consentimiento, cancelación de suscripción, lista de bloqueo, retención y registro en logs.
  • Las colas de lotes cuentan con límites de concurrencia, contrapresión, paneles de control y alertas.
  • Los operadores pueden pausar envíos y revisar intentos ambiguos sin reproducirlos automáticamente.

Enviar un mensaje de WhatsApp

Revise tipos de solicitudes, campos, ejemplos y datos de respuesta.

Configurar webhooks

Verifique firmas y procese entregas repetidas de eventos de forma segura.

Subir contenido multimedia de WhatsApp

Suba archivos multimedia compatibles y reutilice el ID de contenido multimedia devuelto.

Gestionar errores de la API

Analice las respuestas de error y aplique reintentos delimitados.