WhatsApp Cloud API: tu primer mensaje (y los errores que verás)

Lo que necesitas

• Una cuenta de desarrollador de Meta y un portafolio comercial de Meta (el asistente crea uno si hace falta).
• Un teléfono con WhatsApp para recibir los mensajes de prueba.
• curl o cualquier cliente HTTP. Para enviar no necesitas servidor; solo para recibir (webhooks).

Si quieres comparar WhatsApp con otras plataformas: Telegram, Discord o WhatsApp. La arquitectura completa está en nuestra guía de WhatsApp Cloud API.

1. Crea la app y abre API Setup

1. En developers.facebook.com/apps, crea una app y elige el caso de uso de WhatsApp (el asistente habla de conectar con clientes por WhatsApp; Meta cambia el nombre de estas pantallas de vez en cuando).
2. Abre WhatsApp > API Setup. Obtienes: - un número de prueba y su Phone number ID (no es el número en sí), - un WhatsApp Business Account ID, - un token de acceso temporal que caduca pronto (alrededor de un día al momento de escribir).
3. En "To", agrega tu propio número como destinatario y confirma el código que te envía WhatsApp. El número de prueba solo puede escribir a una lista corta de destinatarios verificados.

2. Envía la plantilla hello_world

Las conversaciones iniciadas por la empresa deben empezar con una plantilla aprobada. Toda cuenta nueva tiene la plantilla de ejemplo hello_world:

export WA_TOKEN="EAAG..."              # token temporal de API Setup
export PHONE_ID="1234567890"           # Phone number ID, no el número
export TO="15551234567"              # destinatario en formato internacional, solo dígitos

curl -s "https://graph.facebook.com/v23.0/$PHONE_ID/messages" \
  -H "Authorization: Bearer $WA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"messaging_product\": \"whatsapp\",
    \"to\": \"$TO\",
    \"type\": \"template\",
    \"template\": { \"name\": \"hello_world\", \"language\": { \"code\": \"en_US\" } }
  }"

v23.0 es la versión de la Graph API de los ejemplos de Meta al momento de escribir; usa la que muestre tu panel. Una respuesta correcta trae un messages[0].id que empieza con wamid.. Con ese ID relacionas después los webhooks de estado (enviado, entregado, leído).

3. Responde y envía texto libre

Cuando el destinatario responde a tu plantilla, se abre una ventana de atención de 24 horas. Dentro de ella puedes enviar mensajes normales:

curl -s "https://graph.facebook.com/v23.0/$PHONE_ID/messages" \
  -H "Authorization: Bearer $WA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"messaging_product\": \"whatsapp\",
    \"recipient_type\": \"individual\",
    \"to\": \"$TO\",
    \"type\": \"text\",
    \"text\": { \"body\": \"Hola, esto viene de la Cloud API.\" }
  }"

Tras 24 horas sin mensajes del usuario, vuelves a solo plantillas. Puedes diseñar botones y listas en nuestro constructor de mensajes de WhatsApp.

4. Reemplaza el token temporal

El token temporal sirve para una prueba, no para un bot. Crea un usuario del sistema en la configuración del negocio, asígnale tu app y tu cuenta de WhatsApp y genera un token con los permisos whatsapp_business_messaging y whatsapp_business_management (la guía de inicio de Meta también incluye business_management). Guárdalo como cualquier secreto: mira cómo proteger los tokens de tu bot.

5. Recibe mensajes con un webhook

Para leer respuestas necesitas un endpoint HTTPS que:

1. Responda la verificación GET: si hub.mode es subscribe y hub.verify_token coincide con el valor que elegiste en el panel, devuelve hub.challenge como texto plano.
2. Acepte las notificaciones POST y revise el encabezado X-Hub-Signature-256, un HMAC-SHA256 del cuerpo crudo con tu app secret como clave.
3. Devuelva 200 rápido.

# Esquema con FastAPI
import hmac, hashlib, os
from fastapi import FastAPI, Request, Response

app = FastAPI()

@app.get("/webhook")
def verify(request: Request):
    q = request.query_params
    if q.get("hub.mode") == "subscribe" and q.get("hub.verify_token") == os.environ["WA_VERIFY"]:
        return Response(q.get("hub.challenge"), media_type="text/plain")
    return Response(status_code=403)

@app.post("/webhook")
async def receive(request: Request):
    raw = await request.body()
    sig = "sha256=" + hmac.new(os.environ["WA_APP_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, request.headers.get("X-Hub-Signature-256", "")):
        return Response(status_code=401)
    # encola el payload y responde de inmediato
    return Response(status_code=200)

Luego suscribe la app al campo messages en la configuración de webhooks de WhatsApp. Nuestro generador de firmas ayuda a probar la verificación HMAC en local. Opciones de hosting: desplegar un bot de WhatsApp.

Errores que probablemente verás

Costos

Meta cobra por plantilla entregada, con tarifas que dependen de la categoría y del país del destinatario, y las respuestas de servicio dentro de la ventana de atención han sido gratuitas en el modelo actual. Los precios cambian, así que revisa la página oficial de precios de Meta; nuestra calculadora de costos de WhatsApp ayuda a estimar volúmenes.

Preguntas frecuentes

¿Puedo usar mi número personal de WhatsApp?

Un número registrado en la Cloud API no puede usarse al mismo tiempo en la app normal de WhatsApp ni en WhatsApp Business. Usa un número dedicado para producción.

¿Por qué mi plantilla dio éxito pero nunca llegó?

La API la aceptó, pero la entrega falló después. Revisa el webhook de estado de ese wamid; las fallas llegan ahí con un código de error.

¿Necesito un negocio verificado para empezar?

No para probar con el número de prueba. Los límites de envío más altos y algunas funciones requieren verificación del negocio, según la documentación de Meta.

Fuentes

• Meta for Developers, primeros pasos con WhatsApp Cloud API: developers.facebook.com/docs/whatsapp/cloud-api/get-started
• Meta for Developers, referencia de Messages: developers.facebook.com/docs/whatsapp/cloud-api/reference/messages
• Meta for Developers, códigos de error: developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes
• Meta for Developers, webhooks: developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
• Meta for Developers, precios: developers.facebook.com/docs/whatsapp/pricing