WhatsApp: despachar mensajes de plantilla
Qué resuelve
Sección titulada «Qué resuelve»Despachar desde el sistema de la persona mensajes de plantilla ya aprobados por Meta por el número de WhatsApp de la empresa, y saber qué pasó con cada uno (aceptado, enviado, entregado, leído o fallido, con la causa exacta). Cada despacho queda registrado y se consulta después por su identificador.
La API pública de WhatsApp tiene dos operaciones; todo lo demás lo hace una persona en el panel o llega por webhook. Dilo así a la persona para no prometer de más:
| Tarea | Por dónde |
|---|---|
| Despachar un mensaje de plantilla | API: enviarMensajeWhatsapp |
Consultar un despacho por su id | API: consultarMensajeWhatsapp |
| Saber cómo avanza cada despacho (enviado, entregado, leído, fallido) | Consulta del despacho, o el evento whatsapp.mensaje.estado si la persona lo enciende en el canal |
| Recibir los mensajes que escriben al número | Webhook del canal (evento whatsapp.mensaje.entrante), configurado en el panel |
| Recibir lo que el negocio envía desde la app del celular, si el número está en coexistencia | Webhook del canal (evento whatsapp.mensaje.eco) |
| Enterarse de que el número pasó a otro tenant | Webhook del tenant (evento whatsapp.canal.transferido) |
| Conectar o reconectar el número, crear y aprobar plantillas, configurar el webhook del canal, listar los mensajes del canal, crear la llave | Panel, una persona. No hay operación de API |
La API despacha sólo plantillas aprobadas; no publica una operación de texto libre. Si lo que necesitas es SMS, ve a SMS; si es un formulario que recibe solicitudes, a Comunicación.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- El servicio
WHATSAPP_MENSAJERIAhabilitado en la empresa. Si no, responde403y lo dice. - El número de WhatsApp conectado, desde el panel, en Comunicación, Canales. Un canal sin conectar, o con el token de Meta vencido, responde
422. - Una llave con el rol
WHATSAPP_MENSAJERIA_DESPACHO.FULL-APIno sirve, a propósito: este rol sólo despacha y consulta un despacho. Con esta llave cualquier otra operación (por ejemploPOST …/sms/send) responde403. La crea un administrador de la empresa en el panel, en General → API Keys, eligiendo «Despacho Mensajería WhatsApp» y, para probar, activando «Llave de prueba». Una llave no crea llaves: no hay forma de emitirla por API. La pantalla permite descargarla como JSON (mismo formato quekeys/redcumbre-prueba.json); la persona lo deja enkeys/, por ejemplokeys/whatsapp-prueba.json. No lo leas, no lo imprimas y no le pidas que pegue el secreto en el chat. - Una plantilla aprobada por Meta. Las crea y administra la persona en el panel; se identifica por el par nombre + idioma (
templateName+languageCode). Una plantilla inexistente o no aprobada produce un422. Pídele a la persona el nombre, el idioma y qué variables tiene en cada componente (encabezado, cuerpo, botón). - El
channelId. Va en la ruta y lo obtiene la persona del panel: es el último segmento de la dirección del canal (/<empresa>/comunicacion/canales/<channelId>). La llave no lo lleva adentro. - En modo de prueba no hace falta nada de lo anterior salvo la llave de prueba: el único canal que existe es
canal-whatsapp-de-pruebay sus plantillas de ejemplo (abajo). - Cómo funcionan las dos llaves y qué cambia al pasar a producción: Modo de prueba y producción. Firma, eventos y reintentos de los avisos: Webhooks. Paginación, errores y límites: Reglas comunes.
El canal y las plantillas de prueba
Sección titulada «El canal y las plantillas de prueba»templateName | languageCode | Cuerpo | Variables del cuerpo | Además |
|---|---|---|---|---|
pedido_en_camino | es | Hola, tu pedido {{1}} va en camino. | 1. Número del pedido | Encabezado con material |
recordatorio_de_pago | es | Hola {{1}}, te recordamos que el documento {{2}} vence el {{3}}. | 1. Nombre del cliente · 2. Folio del documento · 3. Fecha de vencimiento | — |
documento_disponible | es | Hola {{1}}, tu documento está disponible. Ábrelo con el botón de abajo. | 1. Nombre del destinatario | Botón de URL con variable |
Con otro canal (incluido el de producción) o con una plantilla fuera de esta tabla, la respuesta es el mismo 404 o 422 de algo que no existe. El teléfono +56222222244 fuerza la entrega fallida.
-
Ubica y lee la operación.
Ventana de terminal redcumbre buscar "enviar un mensaje de whatsapp con plantilla"redcumbre api describir enviarMensajeWhatsappResultado esperado: la operación
enviarMensajeWhatsappcon efectoenvia, la métrica (whatsapp_mensajeria_saliente), el rolWHATSAPP_MENSAJERIA_DESPACHO, el parámetrochannelIdy la clave de repeticiónidempotencyKey, en el cuerpo. -
Despacha un mensaje de prueba. Arma el cuerpo; manda el número internacional completo (
+56912345678o56912345678; sin código de país Meta no lo resuelve).{"destinatario": "+56912345678","templateName": "recordatorio_de_pago","languageCode": "es","componentes": {"cuerpo": {"variables": [{ "posicion": 1, "valor": "Ana" },{ "posicion": 2, "valor": "F-1024" },{ "posicion": 3, "valor": "15-10-2026" }]}},"referenciaExterna": "factura-1024-recordatorio-1","idempotencyKey": "recordatorio-F-1024-1"}Ventana de terminal REDCUMBRE_LLAVE_PRUEBA=keys/whatsapp-prueba.json redcumbre api enviarMensajeWhatsapp --param channelId=canal-whatsapp-de-prueba --cuerpo @mensaje.json --ensayoREDCUMBRE_LLAVE_PRUEBA=keys/whatsapp-prueba.json redcumbre api enviarMensajeWhatsapp --param channelId=canal-whatsapp-de-prueba --cuerpo @mensaje.jsonResultado esperado: el ensayo muestra la petición sin hacerla. La ejecución responde
201y no llama a Meta ni sale ningún mensaje; el registro se escribe igual, marcado de prueba, y cuenta uno en el tope diario de WhatsApp (200 operaciones de prueba al día, que se renueva a las 00:00 de Chile). Leedata.sandbox: es la marca del despacho.{"success": true,"data": {"id": "cmtugtxaq0005se8n63n27jx3","wamid": "wamid.SANDBOX-cmtugtxaq0005se8n63n27jx3","estado": "submitted","destinatarioNormalizado": "56912345678","sandbox": true,"cobrado": false,"noCobradoMotivo": "sandbox","referenciaExterna": "factura-1024-recordatorio-1"},"sandbox": true,"cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }}Guarda
data.id: la consulta recibe eseid, no elwamid.referenciaExterna(hasta 128 caracteres: letras, dígitos,.,_,:y-) vuelve en la respuesta, en la consulta y en cada evento de estado; no pongas datos personales (RUT, teléfono, correo, nombre) porque se registra en el log y se guarda con el mensaje, y no se envía a Meta. Usa unaidempotencyKeyestable y propia de tu sistema (hasta 128 caracteres): repetir el despacho con la misma clave, en la misma empresa y el mismo modo, devuelve el mismo mensaje con el mismo status sin volver a despachar. Sin clave, cada llamada es un despacho. El CLI agrega una si no la pones; para reintentar, repite con--clave <esa clave>. -
Respeta el contrato de variables: posicional por componente. Una plantilla puede tener variables en el encabezado, el cuerpo y el botón de URL, y cada componente numera las suyas desde
{{1}}por separado. Tres reglas:posiciones 1-based y corresponde al{{n}}de ese componente, no del mensaje completo.boton.indiceviaja como cadena ("0"para el primer botón), nunca como número.- Un componente que la plantilla no tiene se omite, no se manda vacío: una plantilla sin botón rechaza el envío que lo incluya. Una plantilla sin variables se despacha sin
componentes.
Con la plantilla de prueba que tiene botón de URL:
{"destinatario": "+56912345678","templateName": "documento_disponible","languageCode": "es","componentes": {"cuerpo": { "variables": [{ "posicion": 1, "valor": "Ana" }] },"boton": { "indice": "0", "variables": [{ "posicion": 1, "valor": "f/abc123XYZ" }] }},"idempotencyKey": "documento-disponible-9001-1"}Un encabezado de imagen lleva
componentes.encabezado.mediaId, el identificador de material que tú ya subiste a Meta (la plataforma lo acepta, no lo produce); Meta lo caduca a los 30 días y pasado el plazo el envío se rechaza con el código131009.variables(en la raíz) sigue aceptado y equivale acomponentes.cuerpo.variables, pero mandarvariablesycomponentesjuntos responde400 WHATSAPP_VARIABLES_Y_COMPONENTES_EXCLUYENTES: no se elige uno en silencio. -
Consulta qué pasó con el despacho.
Ventana de terminal REDCUMBRE_LLAVE_PRUEBA=keys/whatsapp-prueba.json redcumbre api consultarMensajeWhatsapp --param channelId=canal-whatsapp-de-prueba --param id=<data.id>Resultado esperado: el registro del mensaje (plantilla, variables,
estado,wamid,errorCodigoyerrorMensajesi falló,entregadoEn,leidoEn,sandbox,referenciaExterna). En prueba el estado avanza solo:submitted→sent→delivered, y después se llenaleidoEn; con+56222222244termina enfailedcon el código131026. En modo de prueba la consulta sólo lee mensajes marcados de prueba. El valor de las variables del botón de URL viene enmascarado (un*por carácter): no puedes reconstruir el enlace desde la consulta, así que guárdalo de tu lado al despachar. El cuerpo y el encabezado vienen tal cual hasta que vence el plazo de conservación de la cuenta; después los campos que identifican a la persona salen anonimizados, con la misma forma de respuesta.Estado Terminal Qué significa queuedNo La fila se escribió, el despacho está en curso submittedNo Meta aceptó el mensaje. Todavía sin acuse sentNo WhatsApp acusó que salió deliveredSí WhatsApp acusó la entrega, o informó que se leyó. Es hasta donde llega un saliente rejectedSí Meta rechazó el envío por una causa de negocio failedSí, salvo lectura La llamada falló sin respuesta de negocio de Meta, o WhatsApp acusó que no pudo entregarlo El estado nunca retrocede y no existe un estado
read: la lectura se guarda enleidoEn, y una lectura implica la entrega (también desdefailed). -
Mira el mensaje simulado.
Ventana de terminal redcumbre bandeja --canal whatsappResultado esperado: el mensaje retenido en vez de enviado, con el cuerpo y tus variables ya puestas; una variable que no enviaste queda escrita como
{{n}}, para que veas qué faltó. -
Recibe estados y mensajes por webhook (lo configura una persona en el panel). Los avisos del canal van a la dirección y con el secreto que la persona configura en el canal (Canales, tu número, Aviso a tu sistema); no hay operación de API para eso, y el secreto se muestra una sola vez. Si el canal no tiene webhook, los mensajes entrantes se registran igual, y no se entregan a ninguna parte.
Evento Cuándo Qué trae whatsapp.mensaje.estadoUn despacho avanza ( sent,delivered,failed). Viene apagado: la persona lo enciende en la tarjeta «Estado de tus despachos»aviso.avisoId,aviso.mensajeId(eliddel despacho),aviso.referenciaExterna,aviso.estado,aviso.secuencia,leidoEn, y confailedlacausa(codigo,titulo,elegibleParaRespaldo,requiereIntervencion)whatsapp.mensaje.entranteAlguien escribió al número mensaje.wamid(único),mensaje.de,mensaje.tipo,mensaje.cuerpo,mensaje.recibidoEn,contenidoIncluidowhatsapp.mensaje.ecoEl negocio envió desde la app del celular (número en coexistencia). Los despachos de la plataforma no generan eco mensaje.wamid,mensaje.para,mensaje.tipo,mensaje.cuerpo,mensaje.enviadoEnwhatsapp.canal.transferidoEl número pasó a otro tenant con autorización de Meta. Va al webhook del tenant (General → Webhooks) Identificadores, sin enlaces de interfaz Reglas del consumidor:
- Firma: cabecera
X-Webhook-Signature: t=<unix>,v1=<hmac>, HMAC-SHA256 de<t>.<cuerpo crudo>con el secreto del canal. Verifica sobre los bytes crudos (Webhooks). - Al menos una vez y sin orden: deduplica por
avisoId(estado) owamid(entrante, eco) y quédate con el estado de mayorsecuencia. - Responde 2xx a todo, también a lo que ignoras, y rápido (cada intento espera hasta 30 segundos). Toda respuesta que no sea 2xx se reintenta hasta 12 veces en unos 6 minutos; agotados, el aviso queda como perdido y no se vuelve a intentar.
- Tu temporizador manda: si un estado no llega a tiempo, la fuente de verdad es
consultarMensajeWhatsapp. - Un mensaje que no es texto llega sin su contenido (
contenidoIncluido: false,cuerpo: null) y cuenta igual: el archivo queda guardado en WhatsApp y todavía no hay forma de descargarlo desde la API. - En modo de prueba, no dependas del evento de estado. El contrato de la operación dice que no hay eventos en el modo de prueba, y otras guías dicen que llegan al webhook de prueba: lee el estado con
consultarMensajeWhatsapp. Estos eventos no se disparan conredcumbre eventos disparar.
- Firma: cabecera
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»201no es «entregado». Significa que Meta aceptó el mensaje (estado: submitted); todavía no que llegó al teléfono. La entrega confirmada esestado: deliveredenconsultarMensajeWhatsapp(o el eventowhatsapp.mensaje.estadoconaviso.estado: delivered).- En modo de prueba:
201condata.sandbox: true,wamidcon el prefijowamid.SANDBOX-,cobrado: false, el mensaje enredcumbre bandeja --canal whatsappy, al consultar, el estado endelivered(ofailedcon131026si usaste+56222222244). - Un despacho que falla igual queda registrado: el cuerpo del error trae
mensajeId, que es elidque se pasa aconsultarMensajeWhatsapppara leer la causa guardada sin abrir el panel.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 WHATSAPP_VARIABLES_Y_COMPONENTES_EXCLUYENTES | Mandaste variables y componentes juntos | Manda sólo uno |
400 por referenciaExterna | Fuera de la forma permitida (128 caracteres; letras, dígitos, ., _, :, -) | Corrígela; no se envía nada |
400 WHATSAPP_SIN_IDENTIFICADOR_DE_MENSAJE | El error trae mensajeId: el registro del despacho quedó escrito | Consulta el despacho con ese mensajeId antes de reintentar, para no duplicar un envío que no se puede deshacer |
401 | Llave inválida, vencida o revocada | La persona crea otra; no reintentes igual |
403 | El rol de la llave no alcanza (por ejemplo FULL-API), o el servicio WHATSAPP_MENSAJERIA no está habilitado | Usa una llave WHATSAPP_MENSAJERIA_DESPACHO o pide habilitar el servicio |
404 | El canal no existe o no es de tu empresa (indistinguibles); en prueba, tampoco existe fuera del canal de prueba | Revisa el channelId; en prueba usa canal-whatsapp-de-prueba |
409 whatsapp_canal_desvinculado | El número estaba en coexistencia y se desvinculó desde la app. No se escribió ningún mensaje | Un administrador debe volver a conectarlo en el panel |
422 whatsapp_envio_rechazado | Meta rechazó: plantilla inexistente o no aprobada, parámetros que no calzan, o la ventana de conversación de 24 horas cerrada | Lee message (es la causa de Meta, sin traducir) y corrige. No reintentes igual |
422 whatsapp_token_invalido | El token del número venció o fue revocado | No se arregla desde el sistema: el administrador reconecta el número en el panel |
422 whatsapp_channel_sin_credenciales | El canal no está conectado | Ídem: se reconecta desde el panel |
429 whatsapp_limite_alcanzado | Límite de mensajería que Meta asigna al número (no es un límite de la plataforma) | Reintenta con espera creciente, no en bucle ese mismo día |
503 | No se pudo verificar la llave contra el proveedor de identidad. La llave no fue rechazada | Reintenta respetando Retry-After; no rotes la llave |
400 con MODO_PRUEBA_TOPE_DIARIO | Se agotaron las 200 operaciones de prueba de WhatsApp del día | Espera a las 00:00 de Chile |
Otro 5xx | Error de Meta que no cae en las categorías anteriores | Reintenta con espera creciente y la misma idempotencyKey |
En 422, 429 y en el 400 de identificador, el cuerpo trae error (el código para ramificar), message y mensajeId. El 404 del canal y el 401/403 no traen mensajeId: no se llegó a escribir ninguna fila.
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»-
Qué cambia: el mensaje sale de verdad por Meta al teléfono de una persona (métrica
whatsapp_mensajeria_saliente); los mensajes que te escriben y los ecos también cuentan. Lo que cuesta depende de tu plan:redcumbre tarifas enviarMensajeWhatsapp --produccion. Pide a la persona su sí explícito antes del primer despacho de producción. -
Qué hace falta: una llave
WHATSAPP_MENSAJERIA_DESPACHOsin «Llave de prueba» (la crea la persona en General → API Keys), el número conectado, la plantilla aprobada por Meta y elchannelIddel canal de producción, que muestra el panel (ya nocanal-whatsapp-de-prueba). -
El comando:
Ventana de terminal REDCUMBRE_LLAVE_PRODUCCION=keys/whatsapp-produccion.json redcumbre api enviarMensajeWhatsapp --param channelId=<channelId> --cuerpo @mensaje.json --clave <clave-estable> --produccion --confirmar <empresa>No verificado: que las comprobaciones previas que hace el CLI en producción (identidad de la empresa y consumo del plan) las acepte una llave de rol angosto. Si se detiene ahí, el despacho lo hace el código del proyecto, leyendo la llave de su archivo o su variable de entorno.
-
Meta puede reclasificar la categoría de una plantilla (una enviada como utilidad volvió como marketing). El tenant no controla la categoría y es lo que Meta trata y limita distinto: si los despachos empiezan a rechazarse por límites, esa es la primera hipótesis.
-
Datos y secretos: nada de datos personales en
referenciaExterna, y ningún testigo, contraseña ni código de verificación en las variables del cuerpo, que se guardan en claro hasta que vence el plazo de conservación. Ese material va en el botón de URL, cuyo valor la plataforma no retiene. -
Los avisos de producción llegan a una dirección
httpsalcanzable desde internet, firmados con el secreto del canal, que se muestra una sola vez. -
Más detalle: Modo de prueba y producción.