Enviar mensajes con WhatsApp Cloud API: POST /messages | WhatsApp API

El endpoint central de mensajería es POST /{PHONE_NUMBER_ID}/messages. El tipo de payload depende de si envías texto, plantilla, imagen, documento, reacción u otro mensaje compatible. La política de ventanas y plantillas debe resolverse antes de construir el request.

Solicitud de texto

POST https://graph.facebook.com/{VERSION}/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "573001234567",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "Hola, ¿en qué podemos ayudarte?"
  }
}

El destinatario debe estar expresado en el formato aceptado por la API y tu aplicación debe validar los datos antes de enviar. No expongas el token en JavaScript del navegador.

Respuesta y correlación

{
  "messaging_product": "whatsapp",
  "contacts": [{"input": "573001234567", "wa_id": "573001234567"}],
  "messages": [{"id": "wamid...."}]
}

Guarda el wamid junto al ID interno de tu mensaje. Después, los webhooks de estado se correlacionan con ese identificador. Una respuesta HTTP 200 al envío no equivale a “leído”; solo indica que la solicitud fue aceptada en el flujo correspondiente.

Enviar una plantilla

POST https://graph.facebook.com/{VERSION}/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "573001234567",
  "type": "template",
  "template": {
    "name": "nombre_plantilla",
    "language": {"code": "es"}
  }
}

Para plantillas con variables, headers, botones o media, construye components según la plantilla aprobada. No uses una plantilla Marketing como si fuera Utility solo para buscar un costo distinto; el propósito real del mensaje debe coincidir con la categoría y políticas vigentes.

Patrón de envío robusto

Crea registro interno queued con una clave idempotente.
Construye y valida el payload.
Ejecuta el POST con timeout explícito.
Almacena wamid y cambia a accepted/submitted según tu modelo interno.
Actualiza entrega/lectura únicamente con webhooks.
Clasifica fallos antes de decidir reintento.

¿Tu empresa no necesita desarrollar esto?

Optimify ya integra la capa empresarial sobre WhatsApp API

Esta sección existe para equipos que realmente quieren construir o integrar. Si la empresa solo necesita CRM, multiagente, campañas, automatización e IA, MensajAPI recomienda comparar el costo de desarrollo y mantenimiento frente a usar Optimify, que ofrece una plataforma lista y soporte en español.

Ver alternativa gestionada con Optimify

Documentación oficial para mantener la integración actualizada

Versionado: los ejemplos usan {VERSION} en lugar de fijar una versión de Graph API. Sustituye esa variable por una versión vigente y soportada en tu aplicación y revisa cambios antes de actualizar producción.

Cómo enviar mensajes con WhatsApp Cloud API