Skip to main content

​
API Overview

La API de Whaapy te permite enviar mensajes de WhatsApp de forma programática. Está diseñada para ser compatible con Meta WhatsApp Cloud API mientras ofrece shortcuts que simplifican casos de uso comunes.

​
Base URL

https://api.whaapy.com
Todas las rutas documentadas son relativas a esta URL base.

​
Autenticación

Todas las requests requieren un header Authorization con tu API Key: 
Authorization: Bearer wha_TU_API_KEY
Content-Type: application/json
Ver Autenticación para más detalles.

​
Formato Híbrido

Nuestra API acepta dos estilos de request, dándote flexibilidad para usar el formato que prefieras:
Formato simplificado para casos comunes:
{
  "to": "+5215512345678",
  "content": "Hola!"
}
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.

​
Endpoints Disponibles

​
Mensajes

MétodoEndpointDescripciónDocumentación
POST/messages/v1Envía cualquier tipo de mensajeVer docs
POST/messages/v1/:id/retryReintenta un mensaje fallidoVer docs

​
Media

MétodoEndpointDescripciónDocumentación
POST/media/v1Sube archivos a Meta CDNVer docs

​
Tipos de Mensaje Soportados

text

Texto simple

image

JPEG, PNG, WebP

video

MP4 hasta 16MB

audio

MP3, OGG, AAC

document

PDF, Word, Excel

sticker

WebP hasta 500KB

template

Pre-aprobados por Meta

interactive

Botones y listas

location

Coordenadas GPS

contacts

Tarjetas vCard

reaction

Emojis en mensajes

​
Códigos de Respuesta HTTP

CódigoSignificadoDescripción
200OKRequest exitoso
400Bad RequestError de validación en el request
401UnauthorizedAPI Key inválida o faltante
403ForbiddenSin permisos para este scope
404Not FoundRecurso no encontrado
429Too Many RequestsRate limit excedido
500Internal Server ErrorError interno del servidor
Ver Códigos de Error para errores específicos de WhatsApp.

​
Rate Limits

TipoLímite
Mensajes por minuto1,000
Requests por minuto100
Los rate limits pueden variar según tu plan. Contacta soporte para límites personalizados.

​
Límites de Tamaño de Media

TipoFormatosTamaño Máximo
imageJPEG, PNG, WebP5 MB
videoMP4, 3GPP16 MB
audioAAC, MP3, OGG, AMR16 MB
documentPDF, DOC, XLS, PPT, TXT100 MB
stickerWebP500 KB

​
Ventana de 24 Horas

WhatsApp tiene una regla de ventana de 24 horas: solo puedes enviar mensajes de texto libre a usuarios que te han escrito en las últimas 24 horas.
Dentro de la ventana (24h desde último mensaje del usuario):
  • Puedes enviar cualquier tipo de mensaje
  • Texto, imágenes, videos, interactivos, etc.
Fuera de la ventana (>24h sin respuesta):
  • Solo puedes enviar template messages pre-aprobados por Meta
  • Ver Enviar Templates

​
Estructura de Respuesta Exitosa

Todas las respuestas exitosas siguen esta estructura: 
{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+5215512345678", "wa_id": "5215512345678" }
  ],
  "messages": [
    { "id": "uuid-whaapy", "wamid": "wamid.HBgLNTIxNTUx..." }
  ],
  "data": {
    "id": "uuid-del-mensaje",
    "conversationId": "uuid-de-conversacion",
    "messageType": "text",
    "direction": "outbound",
    "status": "sent",
    "createdAt": "2026-01-22T10:30:00Z"
  }
}
CampoDescripción
messaging_productSiempre "whatsapp"
contacts[].wa_idID de WhatsApp del destinatario
messages[].idUUID del mensaje en Whaapy
messages[].wamidID del mensaje en Meta
data.conversationIdUUID de la conversación
data.statussent, delivered, read, o failed

​
Estructura de Respuesta de Error

{
  "error": "message_delivery_failed",
  "message": "Descripción legible del error",
  "code": "131047",
  "action_required": "Acción sugerida",
  "instructions": "Pasos detallados para resolver",
  "data": {
    "id": "uuid-del-mensaje",
    "status": "failed"
  }
}
Ver Códigos de Error para la lista completa.

​
SDKs y Ejemplos

Actualmente no tenemos SDKs oficiales, pero la API es simple de usar con cualquier cliente HTTP: 
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!"}'

​
Próximos Pasos

Autenticación

Configura tu API Key

Enviar Mensaje

Envía tu primer mensaje

Templates

Mensajes fuera de ventana 24h

Códigos de Error

Manejo de errores