Skip to main content
POST
/
messages
/
v1
curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "content": "¡Hola! Gracias por tu mensaje. Te responderemos pronto."
  }'

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+5215512345678", "wa_id": "5215512345678" }
  ],
  "messages": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "wamid": "wamid.HBgLNTIxNTUx..." }
  ],
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "conversationId": "660e8400-e29b-41d4-a716-446655440001",
    "content": "¡Hola! Gracias por tu mensaje.",
    "messageType": "text",
    "direction": "outbound",
    "status": "sent",
    "createdAt": "2026-01-22T10:30:00Z"
  }
}
El endpoint principal para enviar mensajes. Esta página cubre mensajes de texto. Para otros tipos, consulta:

Media

Imágenes, videos, audio, documentos, stickers

Templates

Templates pre-aprobados por Meta

Interactive

Botones y listas interactivas

Ubicación

Coordenadas GPS y direcciones

​
Formato Híbrido

Whaapy acepta dos estilos de request, dándote flexibilidad:
Formato minimalista para casos comunes:
{
  "to": "+5215512345678",
  "content": "¡Hola! Gracias por contactarnos."
}
El estilo Whaapy es más corto y fácil de usar. El estilo Meta es útil si ya tienes código funcionando con la API oficial de WhatsApp.

​
Campos de Destino

Debes proporcionar al menos uno de estos campos para identificar el destinatario:
​
to
string
Número de teléfono con código de país. Ejemplo: +5215512345678
​
phone_number
string
Alias de to. Mismo formato.
​
conversationId
string
UUID de una conversación existente en Whaapy. Útil para responder en conversaciones activas.
Si proporcionas conversationId, Whaapy obtiene automáticamente el número de teléfono de esa conversación.

​
Campos de Contenido (Texto)

​
content
string
Estilo Whaapy. El texto del mensaje a enviar.
​
text
object
Estilo Meta. Objeto con las siguientes propiedades:
  • body (string, requerido): El texto del mensaje
  • preview_url (boolean, opcional): Si mostrar vista previa de URLs

​
Ejemplos

​
Texto Simple (Estilo Whaapy)

curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "content": "¡Hola! Gracias por tu mensaje. Te responderemos pronto."
  }'

​
Texto con Vista Previa de URL (Estilo Meta)

{
  "to": "+5215512345678",
  "type": "text",
  "text": {
    "body": "Mira nuestro catálogo: https://whaapy.com/productos",
    "preview_url": true
  }
}
Con preview_url: true, WhatsApp mostrará una vista previa enriquecida del enlace (imagen, título, descripción) si la URL lo soporta.

​
Responder a Conversación Existente

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Gracias por tu paciencia. Ya tenemos tu pedido listo."
}

​
Respuesta Exitosa

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+5215512345678", "wa_id": "5215512345678" }
  ],
  "messages": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "wamid": "wamid.HBgLNTIxNTUx..." }
  ],
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "conversationId": "660e8400-e29b-41d4-a716-446655440001",
    "content": "¡Hola! Gracias por tu mensaje.",
    "messageType": "text",
    "direction": "outbound",
    "status": "sent",
    "createdAt": "2026-01-22T10:30:00Z"
  }
}

​
Campos de Respuesta

CampoDescripción
messaging_productSiempre "whatsapp"
contactsArray con info del contacto (wa_id es el ID de WhatsApp)
messagesArray con IDs del mensaje (id de Whaapy, wamid de Meta)
data.idUUID del mensaje en Whaapy (usar para retry)
data.conversationIdUUID de la conversación
data.statusEstado: sent, delivered, read, failed

​
Errores Comunes

​
Ventana de 24 Horas Expirada

{
  "error": "message_delivery_failed",
  "message": "La ventana de conversación de 24 horas ha expirado",
  "code": "131047",
  "action_required": "Usar template message",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed"
  }
}
WhatsApp solo permite enviar mensajes de texto libre dentro de las 24 horas posteriores al último mensaje del usuario. Fuera de esta ventana, debes usar un template message.
Ver Códigos de Error para la lista completa de errores.

​
Control de IA (Opcional)

Puedes controlar el comportamiento del agente IA al enviar mensajes usando el campo ai:
​
ai.pause
boolean
Pausar la IA después de enviar este mensaje
​
ai.pauseDuration
number
Duración de la pausa en minutos (default: 5, máximo: 1440)
​
ai.disable
boolean
Desactivar la IA permanentemente en esta conversación

​
Ejemplo: Enviar y Pausar IA

{
  "to": "+5215512345678",
  "content": "Te atiendo personalmente",
  "ai": { "pause": true, "pauseDuration": 30 }
}
Esto es útil cuando integras con sistemas externos (n8n, Zapier, CRMs) y necesitas evitar que la IA responda automáticamente. Ver Agente IA para más opciones.

​
Próximos Pasos

Enviar Media

Imágenes, videos, audio, documentos

Templates

Mensajes fuera de ventana de 24h

Reintentar Mensaje

Reenviar mensajes fallidos

Subir Media

Subir archivos grandes