Tipos de Mensaje del WhatsApp Cloud API: Guía Técnica Completa 2026
Cuando integras WhatsApp Cloud API por primera vez, aparece una confusión que cuesta dinero y tiempo: se habla de “tipos de mensaje” para referirse a dos cosas completamente distintas.
Por un lado están los tipos técnicos — text, image, interactive, template — que determinan qué ve el cliente en su teléfono. Por otro están las categorías de facturación — Marketing, Utilidad, Autenticación, Servicio — que determinan cuánto te cobra Meta.
Son ejes independientes. Un mensaje de tipo template puede pertenecer a cualquiera de las cuatro categorías. Un mensaje de tipo text no tiene categoría en absoluto, porque solo puede enviarse dentro de la ventana de 24 horas.
Esta guía cubre los dos ejes, con los límites reales de cada formato, los códigos de error que verás en producción y las trampas que no aparecen en la documentación oficial.
Eje 1: Los tipos técnicos de mensaje
El campo type del JSON define el formato. Estos son los tipos que puedes enviar a través del endpoint de mensajes.
Mensajes de texto
El más simple y el más usado. Admite hasta 4.096 caracteres.
Tiene un parámetro que mucha gente ignora: preview_url. Si lo activas y el texto contiene un enlace, WhatsApp renderiza la tarjeta de vista previa con el título e imagen del sitio. Si lo dejas apagado, el enlace aparece como texto plano. Para mensajes de venta con un link a tu catálogo, la diferencia en clics es notable.
Mensajes multimedia
Aquí es donde aparecen las primeras sorpresas. Cada formato tiene restricciones estrictas y Meta las rechaza sin ambigüedad:
| Tipo | Formatos aceptados | Límite de tamaño |
|---|---|---|
image | Solo JPEG y PNG | 5 MB |
audio | AAC, AMR, MP3, M4A, OGG (solo códec Opus) | 16 MB |
video | MP4, 3GP (solo H.264 con audio AAC) | 16 MB |
document | PDF, Office, texto plano y otros | 100 MB |
sticker | WebP: 100 KB estático, 500 KB animado | — |
La restricción que más problemas causa es la primera: WebP no es un formato válido para image. Es contraintuitivo porque WebP sí es el formato obligatorio para sticker. Si tu sistema guarda imágenes optimizadas en WebP —como hace prácticamente cualquier stack moderno— y las envías directo al API, recibes el error 131053 y el mensaje nunca llega. La solución es transcodificar a JPEG o PNG antes de enviar.
Lo mismo pasa con el audio: un .ogg con códec Vorbis en lugar de Opus es rechazado, aunque la extensión del archivo sea correcta.
Tanto image, video como document admiten caption — un texto que aparece bajo el archivo. Los documentos además aceptan filename, que controla el nombre que ve el cliente al descargar. Sin él, WhatsApp muestra un identificador ilegible.
Ubicación y contactos
location envía coordenadas con nombre y dirección opcionales. Es lo correcto para compartir la dirección de tu tienda: el cliente toca el mensaje y se le abre su app de mapas.
contacts envía una vCard estructurada — nombre, teléfonos, correos, organización. Útil para pasarle al cliente el contacto directo de un vendedor sin que tenga que copiar números a mano.
Reacciones
El tipo reaction aplica un emoji sobre un mensaje existente, referenciado por su message_id. Enviar el mismo tipo con el emoji vacío elimina la reacción.
Es una herramienta de acuse de recibo sorprendentemente eficiente: confirmar con un 👍 que recibiste un pedido consume mucha menos atención del cliente que un mensaje de texto, y no ocupa espacio en la conversación.
Mensajes interactivos
El tipo interactive es el que convierte una conversación en una interfaz. Tiene varios subtipos:
button — Hasta 3 botones de respuesta rápida. El límite de tres es duro; no hay forma de ampliarlo. Ideal para confirmaciones y bifurcaciones simples (“Confirmar pedido” / “Modificar” / “Cancelar”).
list — Un menú desplegable con secciones y hasta 10 filas por sección. Cada fila tiene título y descripción opcional. Es la opción correcta cuando tienes más de tres alternativas: un catálogo de servicios, horarios disponibles, sucursales.
cta_url — Un botón que abre una URL. Su ventaja sobre poner el link en el texto es doble: se ve como un botón real y el enlace no queda expuesto como cadena larga en el cuerpo del mensaje.
flow — WhatsApp Flows: un formulario nativo que se abre dentro del chat. El cliente completa varios campos sin salir de WhatsApp y recibes la respuesta estructurada. Es lo más cercano a una mini-aplicación dentro de la conversación.
location_request_message — Muestra un botón que pide la ubicación del cliente. Imprescindible para delivery: en vez de pedirle que escriba su dirección, la comparte con un toque.
product y product_list — Envían artículos de tu catálogo de Meta Commerce.
address_message — Formulario de dirección estructurado, disponible únicamente en India y Singapur.
Plantillas
El tipo template merece su lugar aparte porque tiene una propiedad que ningún otro tipo tiene: es el único que puede enviarse fuera de la ventana de 24 horas.
Una plantilla se compone de encabezado (texto, imagen, video, documento o ubicación), cuerpo, pie de página y botones. Debe crearse y ser aprobada por Meta antes de usarse. Cubrimos el proceso completo de creación y aprobación en la guía de WhatsApp Templates.
Los tipos que solo puedes recibir
Estos nunca los envías. Llegan por webhook cuando el cliente actúa, y si tu integración no los contempla, pierdes información real.
button — El cliente tocó un botón de respuesta rápida de una plantilla. La etiqueta que pulsó viene en button.text. Si tu código solo lee text.body, este mensaje llega vacío.
interactive con subtipos de respuesta:
button_reply— respuesta a botones interactivos, conidytitlelist_reply— fila seleccionada del menú, conid,titleydescriptionnfm_reply— respuesta de un Flow, que llega como un JSON con todos los campos del formulario
order — El cliente envió un carrito desde tu catálogo. Incluye los productos, cantidades y precios.
system — Eventos de la plataforma, como que el contacto cambió de número de teléfono. El cuerpo viene en system.body.
unsupported y unknown — Y aquí está la trampa más importante de todo el webhook.
Cuando Meta clasifica un mensaje como no soportado —encuestas, ciertos códigos OTP generados por otras apps, formatos nuevos que el API todavía no expone— no envía el contenido. Solo llega un array errors con la razón. No hay campo de texto que rescatar.
Esto obliga a una decisión de diseño: puedes mostrar un genérico “[Mensaje no soportado]”, o puedes surfacear la razón concreta que da Meta. La segunda opción es la correcta, porque el agente que atiende sabe que ahí hubo algo y puede pedirle al cliente que lo reenvíe de otra forma. Fingir que el mensaje no existió es cómo se pierde una venta sin enterarse.
Los estados de entrega
Los estados no son mensajes: llegan en un array statuses separado dentro del mismo webhook. Son cuatro:
sent— Meta aceptó el mensajedelivered— llegó al teléfono del clienteread— el cliente lo abriófailed— falló, con un código de error asociado
Hay una consecuencia operativa que se subestima constantemente: una respuesta 2xx al enviar no significa que el mensaje se entregó. Significa que Meta lo aceptó en su cola. El fallo real puede llegar segundos o minutos después, de forma asíncrona, por webhook.
Cualquier contador de “enviados” que se calcule en el momento del envío va a mentir. Si mandas una campaña de 174 mensajes y todos devuelven 2xx, tu panel dirá 174 enviados — y los webhooks de failed que llegan después pueden decir otra cosa completamente distinta. Los reportes de campañas masivas tienen que leer el estado final, no la respuesta del envío.
Eje 2: Las categorías de facturación
Este es el segundo eje, y solo aplica a las plantillas. La categoría se declara al crear la plantilla y Meta la audita — si mandas una promoción etiquetada como Utilidad, te la reclasifica.
| Categoría | Qué incluye | Costo |
|---|---|---|
| Marketing | Promociones, ofertas, lanzamientos, newsletters | El más alto |
| Utilidad | Confirmación de pedido, seguimiento de envío, recordatorio de cita, aviso de cuenta | Intermedio |
| Autenticación | Códigos OTP, verificación de cuenta | Bajo, con tarifa aparte para envíos internacionales |
| Servicio | Tus respuestas dentro de la ventana de 24 horas | Sin costo |
Los precios exactos varían por país. Tienes el desglose por mercado en la guía completa de WhatsApp Business API.
La ventana de 24 horas
Aquí está la regla que gobierna todo el modelo:
La ventana de 24 horas la abre el cliente, no tú. Cuando un cliente te escribe, se abre una ventana de servicio de 24 horas. Mientras esté abierta, puedes responder con cualquier tipo de mensaje —texto, imágenes, botones, listas— sin costo por mensaje y sin necesidad de plantilla.
Cuando la ventana se cierra, solo puedes enviar plantillas aprobadas. Si intentas enviar un text fuera de ventana, recibes el error 131047 y el mensaje no sale.
Tres matices que cambian los números:
- Una plantilla de Utilidad enviada dentro de una ventana ya abierta no genera cargo. Si el cliente te escribió hace dos horas y le mandas la confirmación de su pedido, esa plantilla no se cobra.
- Puntos de entrada gratuitos. Si el cliente llega desde un anuncio Click-to-WhatsApp o desde el botón de tu página de Facebook, la ventana es de 72 horas y la conversación no genera cargo.
- Cada mensaje de plantilla se factura de forma individual, no por conversación.
Por qué “antes funcionaba” y ahora no
Esta es la situación más común en soporte, y ahora tienes las dos piezas para entenderla.
Un negocio lleva meses respondiendo mensajes sin ningún problema. Un día lanza su primera campaña con plantilla y todos los envíos fallan con un error de facturación como el 131042.
Lo que pasó no es que algo se rompiera. Mientras solo respondían dentro de la ventana de 24 horas, estaban usando mensajes de categoría Servicio, que no tocan el sistema de cobro de Meta en absoluto. La cuenta podía llevar meses sin moneda ni método de pago configurados y nadie lo notaba.
La campaña con plantilla fue la primera operación facturable de esa cuenta. El tipo técnico de mensaje no cambió nada; el eje de facturación sí. Por eso el diagnóstico correcto ante un fallo masivo de campaña casi nunca está en el contenido del mensaje: está en la configuración de pago de la cuenta de WhatsApp Business.
Códigos de error que vas a ver
Los que aparecen con más frecuencia en producción:
| Código | Significado | Solución |
|---|---|---|
131047 | Fuera de la ventana de 24 h | Usa una plantilla aprobada |
131053 | Formato de medio no soportado | Transcodifica (típicamente WebP a JPEG) |
131042 | Problema de facturación de la cuenta | Configura moneda y método de pago |
131026 | Mensaje no entregable | El número no tiene WhatsApp o no acepta mensajes |
131009 | Valor de parámetro inválido | Formato de número incorrecto |
133010 | Número no registrado | Ejecuta el registro del número en el API |
132000 | Número de parámetros no coincide | Los valores no cuadran con las variables de la plantilla |
132001 | La plantilla no existe | Nombre o idioma incorrectos |
Cómo gestiona CRMWhata todos estos tipos
Trabajar con el API en crudo significa mantener el mapeo completo de tipos, las restricciones de formato, la lógica de la ventana de 24 horas y el manejo asíncrono de estados.
CRMWhata absorbe esa capa. Los mensajes entrantes se normalizan sin importar su tipo: la respuesta de un botón, la fila de una lista, un carrito del catálogo o el envío de un Flow llegan a la bandeja como contenido legible, no como JSON. Los tipos que Meta marca como no soportados se muestran con su razón concreta en vez de desaparecer.
En la salida, las imágenes se transcodifican al formato que Meta acepta antes de enviarse, y el estado de cada mensaje se actualiza en tiempo real conforme llegan los webhooks — incluyendo los fallos que aparecen después de un envío aparentemente exitoso.
Si todavía no has hecho la transición al API oficial, la guía de migración a Cloud API cubre las tres rutas posibles, y la opción de coexistencia te permite mantener la app de WhatsApp Business en el teléfono mientras usas el API.
Preguntas frecuentes
¿Puedo enviar un WebP como imagen?
No. WebP solo es válido para stickers. Como imagen, Meta lo rechaza con el error 131053. Hay que convertirlo a JPEG o PNG.
¿Cuántos botones puede tener un mensaje interactivo? Tres como máximo para botones de respuesta rápida. Si necesitas más opciones, usa una lista, que admite hasta 10 filas por sección.
¿Los mensajes de audio del cliente llegan transcritos? El API entrega el archivo de audio, no texto. La transcripción la tiene que hacer tu plataforma.
¿Qué pasa si respondo justo después de que se cierra la ventana?
El mensaje falla con 131047. Tienes que reabrir la conversación con una plantilla aprobada de la categoría que corresponda.
¿Un 2xx significa que el cliente recibió el mensaje?
No. Significa que Meta aceptó el mensaje en su cola. La entrega real se confirma con el webhook de estado delivered.
¿Las plantillas de Utilidad siempre se cobran? No. Si se envían dentro de una ventana de servicio ya abierta por el cliente, no generan cargo.
Conclusión
Los dos ejes se resumen así: el tipo define qué ve el cliente, la categoría define qué pagas. Confundirlos es lo que produce campañas que fallan enteras sin causa aparente, imágenes que nunca llegan y contadores de envío que no cuadran con la realidad.
Con el mapa completo de tipos, sus límites reales de formato y la lógica de la ventana de 24 horas, la mayoría de los fallos del Cloud API dejan de ser misteriosos y pasan a ser diagnosticables en minutos.
¿Quieres usar todos estos tipos de mensaje sin escribir una línea de código? Prueba CRMWhata y conecta tu número de WhatsApp en minutos.
