El webhook messages

Qué lleva el payload

Uno o más mensajes en una sola entrega, cada uno con el remitente, un id y un tipo. El tipo decide qué otras claves están presentes.

• El número de teléfono de quien envió, y el phone number id del número al que escribieron.
• Un id de mensaje wamid, que es la base de la eliminación de repeticiones.
• Una marca de tiempo unix.
• Un tipo: text, image, audio, video, document, sticker, location, contacts, reaction, button o interactive.
• Para los tipos de medios, un id de medio con el que buscar el archivo, y no los bytes en sí.

Por qué nunca llega hasta nosotros en un número enrutado

Porque el override mueve este campo, junto con smb_message_echoes, al destino que tú indiques.

Meta permite que una app sobrescriba a dónde entrega sus webhooks una cuenta de WhatsApp Business. Nosotros apuntamos ese override a tu URL, lo que saca la ruta de mensajes de nuestra infraestructura por completo. No hay copia, ni cola, ni retención de nuestro lado, porque la entrega nunca llega allí.

Cuando no se define ningún destino, esos eventos caen en nuestro callback por defecto, donde el handler los descarta sin persistir. Esa es la diferencia entre una afirmación sobre almacenamiento y una ruta de código: no hay adónde pueda ir el contenido de las conversaciones.

Confirmar la recepción correctamente

Devuelve 200 antes de hacer el trabajo, no después.

Meta trata una respuesta lenta como un fallo y reintenta la entrega, lo que significa que un handler que procesa dentro de la misma petición va a ver el mismo mensaje más de una vez. Responde de inmediato, pon el payload en una cola o en una tarea en segundo plano, y deja que el trabajo ocurra fuera de la petición.

En serverless esto no es opcional. Una función que responde y luego sigue trabajando puede quedar congelada en el instante en que responde, así que la confirmación y el procesamiento tienen que estar de verdad separados.

Eliminar repeticiones

Por el wamid, siempre, porque repetir la entrega es normal y no excepcional.

El mismo mensaje puede llegar dos veces por motivos que no tienen nada que ver con un fallo de tu lado: una respuesta lenta, un timeout de red, un despliegue justo en medio de la entrega. Guardar los ids ya vistos y saltar los repetidos son unas pocas líneas, y es la diferencia entre que a un cliente le respondan una vez o dos.

En un número con Coexistencia esto importa todavía más, porque smb_message_echoes llega por la misma ruta y un handler que trata cada evento como nuevo va a responder encima de una persona que ya respondió.

Errores comunes

• Procesar antes de devolver 200. Meta reintenta la entrega lenta y tú manejas el mensaje dos veces.
• Saltarse la eliminación de repeticiones. Los reintentos son de diseño, no un caso extremo.
• Esperar los bytes del medio en el payload. Lleva un id de medio con el que buscar el archivo.

Preguntas frecuentes

Sigue leyendo