Documentación de WhatsApp API

Referencia completa de la API REST de WhatsApp. Autenticación, endpoints, webhooks, códigos de error y ejemplos de código.

Autenticación

Todas las solicitudes a la API requieren una clave de API enviada en la cabecera Authorization. Su clave de API se genera al crear una instancia y puede consultarla en su panel de control.

Authorization: Bearer YOUR_API_KEY

Las solicitudes sin una clave de API válida devuelven un error 401 Unauthorized. Las claves de API están limitadas por instancias: cada instancia tiene su propia clave.

URL base

https://api2whats.com

Todos los endpoints son relativos a esta URL base. Use únicamente HTTPS: las solicitudes HTTP son rechazadas.

Enviar mensaje de texto

Envía un mensaje de texto a un número de WhatsApp.

POST /send-text

Cuerpo de la solicitud:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

Parámetros:

  • to (cadena, obligatorio) — Número de teléfono del destinatario con código de país, sin + ni espacios
  • message (cadena, obligatorio) — Contenido del texto, admite Unicode y emoji

Respuesta:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

Enviar imagen

Envía una imagen vía URL o Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

Parámetros:

  • to (cadena, obligatorio) — Número de teléfono del destinatario
  • image (cadena, obligatorio) — URL de la imagen o cadena codificada en Base64
  • caption (cadena, opcional) — Texto descriptivo debajo de la imagen

Enviar vídeo

Envía un archivo de vídeo.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

Enviar audio

Envía un archivo de audio (nota de voz o clip de audio).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

Enviar sticker

Envía una imagen de sticker (formato WebP o PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

Enviar documento

Envía un archivo adjunto (PDF, DOCX, XLSX, etc.).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

Parámetros:

  • to (cadena, obligatorio) — Número de teléfono del destinatario
  • document (cadena, obligatorio) — URL del documento o cadena codificada en Base64
  • filename (cadena, opcional) — Nombre del archivo visible (por defecto, el nombre del archivo de la URL)

Enviar ubicación

Envía un pin de ubicación geográfica.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Configuración de webhooks

Los webhooks permiten a su servidor recibir mensajes entrantes en tiempo real. Configure su URL de webhook a través de la API:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

Cuando alguien envía un mensaje a su número conectado, la API envía una solicitud POST a su URL:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Verifique los webhooks entrantes mediante la cabecera X-Signature incluida en cada solicitud.

Gestión de instancias

Compruebe el estado de conexión de su instancia de WhatsApp:

GET /instance/status

Respuesta:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

Códigos de error

Código HTTPCódigo de errorDescripción
400INVALID_PHONEEl formato del número de teléfono no es válido
400MISSING_FIELDFalta un campo obligatorio en la solicitud
401INVALID_API_KEYLa clave de API no es válida o falta
404INSTANCE_NOT_FOUNDLa instancia no existe o no está conectada
429RATE_LIMIT_EXCEEDEDDemasiadas solicitudes, consulte la cabecera Retry-After
500INTERNAL_ERRORError del servidor, reintente con backoff exponencial

Límites de solicitudes

Los límites de solicitudes varían según el plan:

  • Basic — 100 solicitudes/minuto
  • Professional — 300 solicitudes/minuto
  • Enterprise — 1000 solicitudes/minuto

Cuando se alcanza el límite, la API devuelve 429 Too Many Requests con una cabecera Retry-After que indica cuándo puede reintentarlo.

Ejemplos de código

Hay ejemplos funcionales en PHP, Python, JavaScript y cURL disponibles en nuestra sección de ejemplos de código. Cada ejemplo es un script completo y ejecutable.

Paginación y límites

Al listar recursos (instancias, historial de mensajes), la API admite paginación mediante parámetros de consulta:

GET /messages?page=1&limit=50

Respuesta:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

El tamaño de página por defecto es 50. El máximo es 100. Utilice los parámetros de consulta page y limit para navegar por los resultados.

Envío por lotes

Envíe mensajes a varios destinatarios en una sola llamada a la API. Es más eficiente que realizar solicitudes individuales para cada destinatario.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

El envío por lotes aplica limitación de solicitudes automáticamente. La respuesta incluye el estado de cada mensaje para que sepa cuáles se enviaron correctamente y cuáles fallaron.

Guías para subir archivos multimedia

Al enviar archivos multimedia, siga estas recomendaciones para una entrega óptima:

  • Images — JPEG o PNG, máximo 5MB vía Base64, mayores vía URL. Dimensiones recomendadas: 1200x630 para horizontal, 600x600 para cuadrada.
  • Videos — Formato MP4, máximo 16MB. Se recomienda la codificación H.264 para una mejor compatibilidad.
  • Documents — PDF, DOCX, XLSX, PPTX, TXT. Máximo 100MB vía URL.
  • Audio — Formato MP3 u OGG. Máximo 16MB.
  • Stickers — WebP o PNG, 512x512 píxeles, máximo 500KB.
  • Locations — Coordenadas de latitud/longitud con nombre y dirección opcionales.

Para la codificación Base64, incluya el prefijo data URI: data:image/jpeg;base64,/9j/4AAQ.... Para URLs, asegúrese de que la URL sea públicamente accesible y devuelva la cabecera Content-Type correcta.

Variables de entorno

Guarde su clave de API y configuración en variables de entorno, no en su código:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

Nunca suba su archivo .env al control de versiones. Añádalo a .gitignore. Utilice la configuración de variables de entorno de su plataforma de despliegue para producción.

Versionado

La API se versiona mediante la ruta de la URL. La versión actual es v1 (la predeterminada). Cuando introduzcamos cambios importantes, publicaremos una nueva versión y mantendremos la anterior durante al menos 12 meses.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

Changelog

Mantenemos un changelog público para todos los cambios de la API. Suscríbase al feed RSS del changelog o síganos en GitHub para mantenerse al día. Los cambios importantes se anuncian por correo electrónico a todos los usuarios registrados al menos 30 días antes del despliegue.

¿Necesita ayuda?

Consulte las FAQ para las preguntas más frecuentes. Para problemas concretos, contacte con nuestro equipo de soporte. Respondemos en un plazo de 24 horas.

FAQ

¿Cuál es la longitud máxima de un mensaje?

Los mensajes de texto admiten hasta 4.096 caracteres. Para contenidos más largos, considere enviar un documento o dividir el mensaje en varios envíos.

¿Puedo enviar mensajes a grupos?

Actualmente, la API solo admite mensajería 1 a 1. La mensajería de grupo está en nuestra hoja de ruta para una versión futura.

¿Qué tan rápido se entregan los mensajes?

La mayoría de los mensajes se entregan en 1-3 segundos. El tiempo de entrega depende de la conexión de red del destinatario y del estado de su dispositivo. Los mensajes a dispositivos sin conexión se ponen en cola en WhatsApp y se entregan cuando el dispositivo vuelve a estar en línea.

¿Hay un nivel gratuito?

Puede crear una cuenta y explorar el panel de control gratis. Los planes de pago comienzan en $9.99/mes para el acceso a la API y el envío de mensajes. Contáctenos para obtener acceso de prueba.

¿Qué ocurre si mi clave de API se ve comprometida?

Revoque de inmediato la clave comprometida desde su panel de control y genere una nueva. Todas las sesiones activas que usen la clave antigua serán finalizadas. Recomendamos rotar las claves de API periódicamente y almacenarlas en variables de entorno.

¿Puedo usar la API para mensajería masiva?

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

Página de estado

Consulte el estado de nuestro sistema y la disponibilidad histórica en nuestra página de estado. Ofrecemos actualizaciones en tiempo real durante incidentes y publicamos análisis detallados de cualquier interrupción del servicio.

¿Listo para integrar?

Cree una cuenta y empiece a enviar mensajes en minutos.

Comience gratis