WhatsApp API para desarrolladores — Construya, lance y escale

Una API de WhatsApp centrada en desarrolladores, con endpoints REST limpios, webhooks, ejemplos de código en seis lenguajes e infraestructura que escala con su proyecto.

const response = await fetch('https://api2whats.com/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '971501234567',
    message: 'Hello from my app!'
  })
});
const data = await response.json();
console.log(data.id); // message ID

Por qué los desarrolladores eligen esta API

La mayoría de las soluciones de WhatsApp API están diseñadas primero para usuarios no técnicos y en segundo lugar para desarrolladores. La documentación es escasa, los mensajes de error no ayudan, y usted dedica más tiempo a pelearse con la API que a construir con ella. Nosotros construimos esta API al revés: primero los desarrolladores, todo lo demás después.

Cada endpoint devuelve JSON estructurado con códigos de error claros. Cada solicitud tiene un formato de respuesta predecible. La documentación incluye ejemplos de código funcionales que puede copiar y ejecutar de inmediato. Y el sistema de webhooks entrega los mensajes entrantes a su servidor en tiempo real con payloads firmados para que pueda verificar su autenticidad.

Ya sea que esté construyendo un chatbot de soporte al cliente, un sistema de notificaciones de pedidos, una herramienta de automatización de marketing o una integración personalizada para un cliente, la API se quita de su camino y le permite concentrarse en su código.

Descripción de la arquitectura

La API se sitúa entre su aplicación y los servidores de WhatsApp. Esto es lo que ocurre cuando envía un mensaje:

1. Su aplicación envía una solicitud HTTP POST al endpoint de la API
2. La API autentica su solicitud utilizando la clave de API de la cabecera Authorization
3. El mensaje se enruta a la instancia de WhatsApp correcta (si tiene varias)
4. El mensaje se entrega a través de una conexión WebSocket persistente a WhatsApp
5. Usted recibe una respuesta con el ID del mensaje y el estado de entrega
6. Las actualizaciones de estado posteriores (entregado, leído) se envían a su webhook

Todo el ciclo de ida y vuelta suele tardar menos de 50 milisegundos. No hay navegador involucrado, ni procesamiento de capturas de pantalla, ni manipulación del DOM. La conexión WebSocket es persistente y gestiona automáticamente la reconexión, la renovación de la autenticación y la recuperación de errores.

Referencia de la API REST

Todos los endpoints siguen las convenciones REST. Las solicitudes usan cuerpos JSON. Las respuestas usan JSON. La autenticación se realiza mediante tokens Bearer en la cabecera Authorization.

Envío de mensajes

Gestión de instancias

Webhooks

Integración de webhooks

Los webhooks son la forma de recibir los mensajes entrantes. Cuando alguien envía un mensaje a su número de WhatsApp conectado, la API realiza una solicitud POST a su URL de webhook con los datos del mensaje.

Un payload de webhook se ve así:

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

Su gestor de webhooks procesa estos datos y puede desencadenar cualquier respuesta automatizada. El sistema de webhooks admite lógica de reintento: si su servidor no está disponible temporalmente, la API reintenta la entrega varias veces antes de darse por vencida.

Por seguridad, todos los payloads de webhook incluyen una cabecera X-Signature que puede verificar para asegurarse de que la solicitud realmente proviene de nuestra API y no de un tercero.

Ejemplos de código en seis lenguajes

Proporcionamos ejemplos de código funcionales para cada operación común. Cada ejemplo es un script completo y ejecutable, no un fragmento que le deje adivinando sobre imports, manejo de errores o configuración.

PHP

<?php
$ch = curl_init('https://api2whats.com/send-text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ***',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '971501234567',
        'message' => 'Hello from PHP!',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    'https://api2whats.com/send-text',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'to': '971501234567',
        'message': 'Hello from Python!',
    }
)
print(response.json())

JavaScript (Node.js)

const response = await fetch('https://api2whats.com/send-text', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        to: '971501234567',
        message: 'Hello from Node.js!',
    }),
});
const data = await response.json();
console.log(data);

Manejo de errores

La API utiliza códigos de estado HTTP estándar y devuelve respuestas de error estructuradas:

{
    "success": false,
    "error": {
        "code": "INSTANCE_DISCONNECTED",
        "message": "The WhatsApp instance is not connected"
    }
}

Los códigos de error más comunes incluyen:

• 401 Unauthorized — Clave de API no válida o ausente
• 400 Bad Request — Campos obligatorios ausentes o datos no válidos
• 404 Not Found — La instancia o el recurso no existe
• 429 Too Many Requests — Límite de solicitudes excedido
• 500 Internal Server Error — Algo salió mal de nuestro lado (poco frecuente)

Seguridad de los webhooks

Cada solicitud de webhook incluye una cabecera X-Signature que contiene una firma HMAC-SHA256 del cuerpo de la solicitud. Su gestor de webhooks debe verificar esta firma para asegurarse de que la solicitud realmente proviene de nuestra API y no de un tercero.

// Node.js webhook signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const sig = req.headers['x-signature'];
    const body = JSON.stringify(req.body);

    if (!verifySignature(body, sig, WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // Process the message...
    res.json({ success: true });
});

Pruebas y depuración

La API proporciona varias herramientas para probar y depurar su integración:

• Registros del panel de control — Vea todas las solicitudes a la API y sus respuestas en tiempo real desde su panel de control
• Endpoint de prueba de webhook — Envíe un webhook de prueba para verificar que su gestor funciona correctamente
• Seguimiento del estado de los mensajes — Consulte el estado de cualquier mensaje por su ID
• Monitorización de la tasa de errores — Realice un seguimiento de las tasas de error de su API a lo largo del tiempo en el panel de control

Recomendamos empezar con una instancia de prueba conectada a su número personal. Envíe mensajes de prueba, verifique los webhooks y compruebe el manejo de errores antes de pasar a tráfico de producción.

Mejores prácticas para desarrolladores

• Almacene las claves de API de forma segura — Use variables de entorno, no cadenas escritas en el código. Nunca suba las claves de API al control de versiones.
• Maneje los errores con elegancia — Implemente lógica de reintento con backoff exponencial para errores transitorios (5xx, tiempos de espera de red).
• Valide las firmas de los webhooks — Nunca confíe en solicitudes de webhook sin verificar. Compruebe siempre la cabecera X-Signature.
• Use pooling de conexiones — Reutilice las conexiones HTTP entre solicitudes en lugar de crear una nueva para cada llamada a la API.
• Supervise los límites de solicitudes — Compruebe la cabecera X-RateLimit-Remaining e implemente una limitación proactiva al acercarse a los límites.
• Registre todo — Guarde los pares solicitud/respuesta para depurar. Oculte los datos sensibles (números de teléfono, contenido de los mensajes) en los registros de producción.

Límites de solicitudes

Los límites de solicitudes se aplican por clave de API y varían según el plan. La API devuelve un código de estado 429 con una cabecera Retry-After cuando alcanza el límite. Estos son los valores por defecto:

• Plan Basic — 100 solicitudes por minuto
• Plan Professional — 300 solicitudes por minuto
• Plan Enterprise — 1000 solicitudes por minuto

Si alcanza los límites de solicitudes de forma constante, considere actualizar su plan o agrupar solicitudes siempre que sea posible.

Formatos de payload de los webhooks

Los mensajes entrantes llegan en formatos diferentes según el tipo de mensaje:

Mensaje de texto

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hello!",
    "type": "text",
    "timestamp": 1691234567
  }
}

Mensaje de imagen

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F7",
    "from": "971501234567",
    "type": "image",
    "caption": "Check this out!",
    "mediaUrl": "https://api2whats.com/media/...",
    "mimeType": "image/jpeg",
    "timestamp": 1691234568
  }
}

Actualización de estado

{
  "event": "status",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "delivered",
    "timestamp": 1691234600
  }
}

Los valores de estado incluyen: sent (entregado a WhatsApp), delivered (llegó al dispositivo) y read (abierto por el destinatario).

Cómo empezar

1. Cree una cuenta (gratis, sin tarjeta de crédito)
2. Elija un plan desde la página de precios
3. Cree una instancia desde su panel de control
4. Conecte su número de teléfono mediante código QR o código de emparejamiento
5. Lea la documentación completa de la API
6. Envíe su primer mensaje y empiece a construir

Comunidad y soporte

Únase a nuestra comunidad de desarrolladores para obtener ayuda, compartir integraciones y mantenerse al día sobre las nuevas funcionalidades. Tenemos una comunidad activa de desarrolladores que crean integraciones de WhatsApp en todos los sectores.

• Documentación — Referencia completa de la API con ejemplos funcionales
• Ejemplos de código — Scripts completos y ejecutables en PHP, Python, JavaScript y cURL
• Soporte por correo electrónico — Respuesta en un plazo de 24 horas para todos los niveles de plan
• Registros del panel de control — Visibilidad en tiempo real de las solicitudes a la API y las entregas de webhook
• Página de estado — Estado del sistema en vivo e historial de incidentes

Ya sea que esté construyendo su primera integración de WhatsApp o escalando una existente, nuestros recursos y nuestro equipo de soporte están aquí para ayudarle a tener éxito.