Ir al contenido

WhatsApp: despachar mensajes de plantilla

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:

TareaPor dónde
Despachar un mensaje de plantillaAPI: enviarMensajeWhatsapp
Consultar un despacho por su idAPI: 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úmeroWebhook 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 coexistenciaWebhook del canal (evento whatsapp.mensaje.eco)
Enterarse de que el número pasó a otro tenantWebhook 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 llavePanel, 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.

  • El servicio WHATSAPP_MENSAJERIA habilitado en la empresa. Si no, responde 403 y 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-API no sirve, a propósito: este rol sólo despacha y consulta un despacho. Con esta llave cualquier otra operación (por ejemplo POST …/sms/send) responde 403. 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 que keys/redcumbre-prueba.json); la persona lo deja en keys/, por ejemplo keys/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 un 422. 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-prueba y 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.
templateNamelanguageCodeCuerpoVariables del cuerpoAdemás
pedido_en_caminoesHola, tu pedido {{1}} va en camino.1. Número del pedidoEncabezado con material
recordatorio_de_pagoesHola {{1}}, te recordamos que el documento {{2}} vence el {{3}}.1. Nombre del cliente · 2. Folio del documento · 3. Fecha de vencimiento—
documento_disponibleesHola {{1}}, tu documento está disponible. Ábrelo con el botón de abajo.1. Nombre del destinatarioBotó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.

  1. Ubica y lee la operación.

    Ventana de terminal
    redcumbre buscar "enviar un mensaje de whatsapp con plantilla"
    redcumbre api describir enviarMensajeWhatsapp

    Resultado esperado: la operación enviarMensajeWhatsapp con efecto envia, la métrica (whatsapp_mensajeria_saliente), el rol WHATSAPP_MENSAJERIA_DESPACHO, el parámetro channelId y la clave de repetición idempotencyKey, en el cuerpo.

  2. Despacha un mensaje de prueba. Arma el cuerpo; manda el número internacional completo (+56912345678 o 56912345678; 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 --ensayo
    REDCUMBRE_LLAVE_PRUEBA=keys/whatsapp-prueba.json redcumbre api enviarMensajeWhatsapp --param channelId=canal-whatsapp-de-prueba --cuerpo @mensaje.json

    Resultado esperado: el ensayo muestra la petición sin hacerla. La ejecución responde 201 y 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). Lee data.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 ese id, no el wamid. 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 una idempotencyKey estable 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>.

  3. 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:

    • posicion es 1-based y corresponde al {{n}} de ese componente, no del mensaje completo.
    • boton.indice viaja 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ódigo 131009. variables (en la raíz) sigue aceptado y equivale a componentes.cuerpo.variables, pero mandar variables y componentes juntos responde 400 WHATSAPP_VARIABLES_Y_COMPONENTES_EXCLUYENTES: no se elige uno en silencio.

  4. 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, errorCodigo y errorMensaje si falló, entregadoEn, leidoEn, sandbox, referenciaExterna). En prueba el estado avanza solo: submitted → sent → delivered, y después se llena leidoEn; con +56222222244 termina en failed con el código 131026. 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.

    EstadoTerminalQué significa
    queuedNoLa fila se escribió, el despacho está en curso
    submittedNoMeta aceptó el mensaje. Todavía sin acuse
    sentNoWhatsApp 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 lecturaLa 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 en leidoEn, y una lectura implica la entrega (también desde failed).

  5. Mira el mensaje simulado.

    Ventana de terminal
    redcumbre bandeja --canal whatsapp

    Resultado 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ó.

  6. 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.

    EventoCuándoQué 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 (el id del despacho), aviso.referenciaExterna, aviso.estado, aviso.secuencia, leidoEn, y con failed la causa (codigo, titulo, elegibleParaRespaldo, requiereIntervencion)
    whatsapp.mensaje.entranteAlguien escribió al númeromensaje.wamid (único), mensaje.de, mensaje.tipo, mensaje.cuerpo, mensaje.recibidoEn, contenidoIncluido
    whatsapp.mensaje.ecoEl negocio envió desde la app del celular (número en coexistencia). Los despachos de la plataforma no generan ecomensaje.wamid, mensaje.para, mensaje.tipo, mensaje.cuerpo, mensaje.enviadoEn
    whatsapp.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) o wamid (entrante, eco) y quédate con el estado de mayor secuencia.
    • 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 con redcumbre eventos disparar.
  • 201 no es «entregado». Significa que Meta aceptó el mensaje (estado: submitted); todavía no que llegó al teléfono. La entrega confirmada es estado: delivered en consultarMensajeWhatsapp (o el evento whatsapp.mensaje.estado con aviso.estado: delivered).
  • En modo de prueba: 201 con data.sandbox: true, wamid con el prefijo wamid.SANDBOX-, cobrado: false, el mensaje en redcumbre bandeja --canal whatsapp y, al consultar, el estado en delivered (o failed con 131026 si usaste +56222222244).
  • Un despacho que falla igual queda registrado: el cuerpo del error trae mensajeId, que es el id que se pasa a consultarMensajeWhatsapp para leer la causa guardada sin abrir el panel.
Si vesSignificaQué haces
400 WHATSAPP_VARIABLES_Y_COMPONENTES_EXCLUYENTESMandaste variables y componentes juntosManda sólo uno
400 por referenciaExternaFuera de la forma permitida (128 caracteres; letras, dígitos, ., _, :, -)Corrígela; no se envía nada
400 WHATSAPP_SIN_IDENTIFICADOR_DE_MENSAJEEl error trae mensajeId: el registro del despacho quedó escritoConsulta el despacho con ese mensajeId antes de reintentar, para no duplicar un envío que no se puede deshacer
401Llave inválida, vencida o revocadaLa persona crea otra; no reintentes igual
403El rol de la llave no alcanza (por ejemplo FULL-API), o el servicio WHATSAPP_MENSAJERIA no está habilitadoUsa una llave WHATSAPP_MENSAJERIA_DESPACHO o pide habilitar el servicio
404El canal no existe o no es de tu empresa (indistinguibles); en prueba, tampoco existe fuera del canal de pruebaRevisa el channelId; en prueba usa canal-whatsapp-de-prueba
409 whatsapp_canal_desvinculadoEl número estaba en coexistencia y se desvinculó desde la app. No se escribió ningún mensajeUn administrador debe volver a conectarlo en el panel
422 whatsapp_envio_rechazadoMeta rechazó: plantilla inexistente o no aprobada, parámetros que no calzan, o la ventana de conversación de 24 horas cerradaLee message (es la causa de Meta, sin traducir) y corrige. No reintentes igual
422 whatsapp_token_invalidoEl token del número venció o fue revocadoNo se arregla desde el sistema: el administrador reconecta el número en el panel
422 whatsapp_channel_sin_credencialesEl canal no está conectadoÍdem: se reconecta desde el panel
429 whatsapp_limite_alcanzadoLí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
503No se pudo verificar la llave contra el proveedor de identidad. La llave no fue rechazadaReintenta respetando Retry-After; no rotes la llave
400 con MODO_PRUEBA_TOPE_DIARIOSe agotaron las 200 operaciones de prueba de WhatsApp del díaEspera a las 00:00 de Chile
Otro 5xxError de Meta que no cae en las categorías anterioresReintenta 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.

  • 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_DESPACHO sin «Llave de prueba» (la crea la persona en General → API Keys), el número conectado, la plantilla aprobada por Meta y el channelId del canal de producción, que muestra el panel (ya no canal-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 https alcanzable desde internet, firmados con el secreto del canal, que se muestra una sola vez.

  • Más detalle: Modo de prueba y producción.