Envía tu primer mensaje con la WhatsApp Cloud API de Meta

Al terminar vas a haber enviado tu primer mensaje de WhatsApp con la API oficial de Meta, usando el número de prueba y el token temporal que la propia plataforma te da. Es el punto de partida para automatizar de verdad: una vez que mandas un mensaje con un request HTTP, puedes conectarlo a tu backend, a un bot conversacional o a un orquestador y armar flujos completos sin depender de plataformas intermedias que cobran por mensaje.

El problema que cierra esta lección es el de la fricción al empezar. WhatsApp es el canal de mensajería más usado en muchos países, pero la documentación oficial está dispersa y la curva de aprendizaje asusta: cuentas de Meta, cuentas de WhatsApp Business, números de prueba, tokens temporales, plantillas aprobadas, ventanas de 24 horas, webhooks. La forma de saltar esa fricción es lo que hacemos aquí: ignorar todo lo que no necesitas para el primer mensaje y montar la receta mínima que funciona en treinta minutos.

Realmente treinta minutos basta si te lees bien los nombres de campos antes de copiar el comando. El paso lento suele ser entender el formato del número del destinatario (sin ”+”, sin espacios, sin guiones) y dónde encontrar el Phone Number ID dentro del panel de Meta. Lo demás es pegar valores y disparar el request.

Antes de empezar

Necesitas una cuenta de Facebook/Meta activa, porque Meta for Developers usa esa identidad para autenticar. Si nunca entraste a developers.facebook.com, la primera vez te pedirá aceptar las condiciones de desarrollador; es un trámite rápido. Si te falta alguno de los requisitos del frontmatter, primero abre la cuenta de desarrollador y verifica que tienes curl instalado en tu terminal (en Mac y Linux suele venir por defecto; en Windows puedes usar PowerShell con Invoke-WebRequest o instalar curl manualmente).

Conviene tener a mano el teléfono donde recibirás el mensaje de prueba: vas a tener que verificarlo por un código SMS o llamada cuando lo cargues como destinatario. Y mentalmente prepárate para que los nombres de menús del panel de Meta cambien con el tiempo; la lección describe el flujo en general, pero los textos exactos pueden moverse entre rediseños. Si te pierdes navegando, busca “WhatsApp Cloud API quickstart” dentro del panel.

El recorrido completo

El primer paso, crear la app en Meta for Developers, es el más burocrático. Entras a developers.facebook.com, inicias sesión, vas a “Mis Apps” y creas una nueva de tipo Business. El nombre es interno (no lo verá nadie fuera), así que algo como “Pruebas WhatsApp” basta. Esta app es el contenedor lógico: dentro de ella vas a habilitar el producto WhatsApp y, más adelante, otros productos si quisieras añadir Messenger o Instagram.

Añadir el producto WhatsApp es donde la magia empieza. Meta te crea automáticamente una cuenta de WhatsApp Business asociada y un número de prueba que pertenece a Meta, no a ti. Ese número es una bendición para empezar: te permite enviar mensajes sin tener que registrar y verificar un número real (proceso que dura días y exige documentación de tu empresa). El número de prueba tiene limitaciones (solo envía a destinatarios cargados, una cuota mensual modesta), pero es perfecto para esta lección.

Copiar el Phone Number ID y el token temporal es el paso clave. El Phone Number ID es un identificador numérico largo que representa al número de prueba dentro de la API; no es el número de teléfono en sí, sino su ID interno. El token de acceso temporal es una cadena larga que sirve como llave para autenticar tus requests; vence en pocas horas, así que si pasa un rato entre que lo copias y disparas el comando, puede que tengas que regenerarlo. Ambos valores aparecen en la sección de inicio rápido de la API de WhatsApp dentro del panel.

Añadir tu número como destinatario de prueba es obligatorio porque Meta no deja enviar a cualquier número en modo prueba. En la misma pantalla del paso anterior hay una sección para gestionar destinatarios; ahí añades tu teléfono real (formato internacional). Meta envía un código por WhatsApp o SMS al número, lo introduces para verificarlo, y queda autorizado para recibir mensajes desde este número de prueba. Sin este paso, el request del paso 5 fallaría con un error de destinatario no permitido.

Enviar el mensaje con la API es la parte técnica. Coges el comando curl del frontmatter y reemplazas tres cosas: PHONE_NUMBER_ID por el identificador del paso 3, ACCESS_TOKEN por el token del mismo paso, y el número del campo to por tu teléfono en formato internacional sin signos. La versión del endpoint (v23.0 en el ejemplo) va cambiando; revisa la doc para confirmar cuál es la vigente cuando estás haciendo la prueba. El cuerpo del request usa una plantilla preexistente llamada hello_world en inglés, que Meta ya tiene aprobada para todas las cuentas nuevas.

Verificar la entrega es lo último y lo más satisfactorio. Si el request devuelve un JSON con un campo messages que contiene un id, Meta ha aceptado el envío y debería llegarte el mensaje en cuestión de segundos al WhatsApp del teléfono que cargaste como destinatario. Si pasan varios segundos y no llega, abre la pestaña de logs de mensajes en el panel de Meta para ver el estado: enviado, entregado, leído o rechazado. Si rechazado, el log suele explicar la razón.

Llegado este punto entiendes los cuatro bloques fundamentales de la Cloud API: una app de Meta, un número (de prueba o propio), un token y un request HTTP. Todo lo que vendrá después (webhooks, plantillas propias, números reales, tokens permanentes) son variaciones sobre estos mismos bloques.

Cómo saber que cada parte funciona

Tras crear la app, en “Mis Apps” debe aparecer con su nombre y tipo Business. Tras añadir el producto WhatsApp, ese producto aparece en el menú lateral de la app con sus subsecciones (Quickstart, Phone Numbers, Templates). Tras copiar credenciales, deberías tener un Phone Number ID numérico largo y un token que empieza por una cadena tipo EAA.... Tras añadir tu número como destinatario, debe aparecer en la lista de destinatarios verificados con un check verde o equivalente.

La señal definitiva de que todo funciona es doble: el request devuelve un JSON con messages[0].id y, segundos después, tu WhatsApp suena con el mensaje “Hello World” (o el contenido que tenga la plantilla hello_world en la versión vigente). Si la primera condición se cumple pero el mensaje no llega, lo más probable es que el teléfono no sea exactamente el verificado o que esté mal el formato del campo to.

Errores frecuentes y cómo salir de ellos

• El request devuelve error 190 o de token. El token temporal venció (dura pocas horas). Vuelve a la sección de inicio rápido en el panel de Meta y genera uno nuevo. Para evitar esto en serio, genera un token permanente con un System User cuando dejes la fase de pruebas.
• Error “recipient not in allowed list” o similar. En modo de prueba solo se puede enviar a números cargados como destinatario de prueba. Añade y verifica tu número en la pantalla de inicio rápido, no en otra sección del panel.
• No llega el mensaje aunque el request salió bien. Si usaste texto libre para iniciar la conversación, no va a entregarse: Meta exige que el primer mensaje saliente sea una plantilla aprobada. Usa hello_world para la primera prueba.
• Error de versión del endpoint. La versión de la API (v23.0 en el ejemplo) cambia con el tiempo. Revisa en la documentación oficial cuál es la vigente y reemplázala en la URL del request.
• Número de destino rechazado. Tiene que ir en formato internacional sin ”+”, espacios ni guiones (por ejemplo, 34666123456 para un móvil español). Si pones el signo más o lo separas en bloques, Meta lo rechaza silenciosamente o lo entrega mal.
• El request devuelve 401 Unauthorized. El header de autorización está mal formado. Confirma que el formato sea Authorization: Bearer ACCESS_TOKEN con un espacio entre Bearer y el token, y que el token sea el actual, no uno antiguo copiado de otra sesión.

Variaciones útiles

Si tu objetivo es probar el concepto antes de meterte en webhooks y backends, la receta del frontmatter es suficiente: envías un mensaje, ves que llega y entiendes el flujo. Si tu objetivo es montar un bot real, sustituye el token temporal por uno permanente generado con un System User, registra tu propio número, verifica el negocio y configura un webhook (URL pública con HTTPS) que reciba los mensajes entrantes y dispare la respuesta.

Para casos sencillos (avisos, OTP, recordatorios) puedes mantener el envío como simple request HTTP desde tu backend o desde un orquestador como n8n o Make. Para conversaciones complejas con varios turnos, conviene una capa intermedia que gestione el estado del chat (qué le dijiste antes al usuario, en qué punto de un flujo está). Y si todo lo que necesitas es disparar avisos cuando pasa algo en tu sistema, una integración mínima con un servicio de cron (como los cron jobs de Render de otra lección) cubre el caso entero sin webhook.

Siguiente paso

Cuando hayas enviado tu primer mensaje, los siguientes pasos lógicos son: generar un token permanente con un System User para que tu servidor pueda enviar sin que el token caduque cada pocas horas; configurar un webhook con URL HTTPS pública para recibir mensajes entrantes y estados de entrega; crear tus propias plantillas y enviarlas a aprobar para tus casos reales (avisos transaccionales, OTP, seguimiento de pedidos); y registrar un número propio y verificar el negocio para pasar de prueba a producción. Para orquestar todo esto sin escribir un backend desde cero, conecta la API a un servicio como n8n o Make. Y si quieres montar la receta dentro de un proyecto web completo, combínala con las lecciones de despliegue y de creación de web con varias IAs para cerrar el flujo entero.