API de ViaWA

Qué es y qué no es

• Los mensajes salen desde el WhatsApp que vinculaste en tu cuenta de ViaWA, no desde un número de empresa.
• Es la misma cola que usa la app: un mensaje por API se programa como cualquiera, así que tiene los mismos límites y protecciones (tope diario, período de calentamiento de las cuentas nuevas, detección de envíos masivos y chequeo de que el número exista en WhatsApp).
• No es la API oficial de WhatsApp Business ni un producto de Meta. Usa el mismo protocolo que WhatsApp Web, por lo que rige lo que explicamos en Seguridad y datos sobre el riesgo de uso.
• Necesitás tu WhatsApp vinculado y una suscripción activa (o acceso por invitación).

Empezar en 3 pasos

1. Entrá a la app, andá a Configuración → Acceso por API y creá una clave con el nombre del sistema que la va a usar.
2. Copiala en ese momento: se muestra una sola vez. Nosotros solo guardamos un hash, no podemos recuperarla.
3. Mandá tu primer mensaje con el ejemplo de abajo.

Autenticación

Todos los pedidos van a https://viawa.onrender.com y llevan la clave en el header Authorization. Las claves empiezan con viawa_sk_. La sesión de la app no sirve en la API, ni al revés.

Authorization: Bearer viawa_sk_TU_CLAVE

Enviar o programar un mensaje

POST /v1/messages

curl -X POST https://viawa.onrender.com/v1/messages \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+54 9 11 5145-6236",
    "text": "Hola {{nombre}}, te esperamos mañana a las 10.",
    "sendAt": "2026-10-01T09:30:00-03:00"
  }'

const res = await fetch("https://viawa.onrender.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIAWA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+54 9 11 5145-6236",
    text: "Tu pedido salió de camino.",
    // sendAt es opcional: sin él, se envía en el próximo minuto.
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.id, data.status); // "pending"

import os, requests

res = requests.post(
    "https://viawa.onrender.com/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['VIAWA_API_KEY']}"},
    json={
        "to": "+54 9 11 5145-6236",
        "text": "Tu turno es mañana a las 10.",
        "sendAt": "2026-10-01T09:30:00-03:00",
    },
    timeout=15,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["id"], data["status"])  # pending

{
  "id": "cmubvadd000018z7t5gaqnaq9",
  "to": "5491151456236",
  "contactId": "cmtz0kpve037jg92mkt4aoikq",
  "status": "pending",
  "sendAt": "2026-10-01T12:30:00.000Z",
  "sentAt": null,
  "attemptCount": 0,
  "lastError": null,
  "lastErrorAt": null,
  "nextRetryAt": null,
  "createdAt": "2026-09-21T23:19:20.100Z"
}

Consultar el estado de un mensaje

GET /v1/messages/:id devuelve el mismo objeto de arriba, actualizado.

curl https://viawa.onrender.com/v1/messages/ID_DEL_MENSAJE \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE"

• Si un envío falla por un error de WhatsApp, se reintenta hasta 3 veces con 10 minutos entre intentos; attemptCount y nextRetryAt lo reflejan. Si el número no está en WhatsApp, falla directamente.
• Si tu WhatsApp está desconectado en ese momento, el mensaje espera como pending y sale cuando vuelva la conexión.
• Consultá el estado con calma: con el ritmo de la cola no hace falta más de una vez cada varios segundos.

GET /v1/messages?status=pending|sent|failed&limit=25&cursor=… lista mensajes por estado (por defecto pending; hasta 100 por página). La respuesta trae items y nextCursor (null si no hay más): pasalo como cursor para la página siguiente.

curl "https://viawa.onrender.com/v1/messages?status=failed&limit=25" \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE"

Contactos

• GET /v1/contacts?search=… lista tus contactos; search filtra por nombre, apellido o teléfono. Cada uno trae id, firstName, lastName, fullName, description, phone (solo dígitos, con código de país), formattedPhone, createdAt y variables (los valores de tus variables personalizadas para ese contacto, por ejemplo { "turno": "martes 10hs" }). Los valores se cargan desde la app, en cada contacto.
• POST /v1/contacts crea uno: phone y firstName obligatorios; lastName y description opcionales. Devuelve 201, o 409 contact_exists si el número ya está.

# Listar / buscar
curl "https://viawa.onrender.com/v1/contacts?search=fuschino" \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE"

# Crear
curl -X POST https://viawa.onrender.com/v1/contacts \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+54 9 11 2222-3333", "firstName": "Ana", "lastName": "Ruiz" }'

Límites

• 60 pedidos por minuto por clave. Al pasarte, la API responde 429 con el header Retry-After (segundos). Cada clave tiene su propio cupo.
• Hasta 5 claves activas por cuenta.
• Los límites de la cuenta (tope diario de mensajes y calentamiento de las cuentas nuevas) valen igual que en la app. Un mensaje que los excede se reprograma en vez de enviarse de golpe.

Envíos masivos

Si mandás el mismo mensaje a 11 contactos distintos o más en menos de una hora, ese patrón se parece al de un envío masivo y aumenta el riesgo para tu cuenta de WhatsApp. Para protegerte, la API responde 409 broadcast_confirm_required hasta que confirmes explícitamente que sabés lo que hacés, repitiendo el pedido con "confirmBulk": true. Si lo que necesitás es una difusión, la app tiene un flujo pensado para eso (ritmo escalonado y vista previa).

curl -X POST https://viawa.onrender.com/v1/messages \
  -H "Authorization: Bearer viawa_sk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+5491122223333", "text": "Aviso importante", "confirmBulk": true }'

Errores

Todos los errores tienen la misma forma y un código estable para que lo trates en tu programa:

{
  "error": {
    "code": "bad_request",
    "message": "La fecha y hora de envío deben ser futuras."
  }
}

Buenas prácticas

• Guardá la clave como un secreto: en una variable de entorno o un gestor de secretos, nunca en el código ni en el navegador de tus clientes. Quien la tenga puede enviar mensajes desde tu cuenta.
• Una clave por sistema, con un nombre que lo identifique. Así, si hay que cortar el acceso de uno, no afecta a los demás.
• Revocala ante cualquier sospecha desde Configuración: deja de funcionar al instante y los mensajes ya programados no se cancelan.
• Llamá a la API desde tu servidor, no desde el frontend de una web pública.
• Tratá los códigos de error, no el texto del mensaje: el texto puede mejorar con el tiempo, el code no cambia.
• Mandá solo a personas que esperan tu mensaje: es lo que más cuida a tu número de WhatsApp.