Volver al inicio

Wando API

v1 — REST API publica

Integra Wando con tus sistemas existentes. Lee mensajes pendientes, envia respuestas automaticas, consulta contactos y simula mensajes entrantes para testing.

Spec OpenAPI: importa toda la API en Postman o Insomnia con un clic usando https://tu-dominio.com/api/v1/openapi (en Postman: Import → pegar la URL).

Autenticacion

Todos los endpoints requieren el header X-API-Key con una key valida. Las keys se generan desde Configuracion → API Keys en el panel de Wando.

curl -H "X-API-Key: tu-api-key-aqui" \
  https://tu-dominio.com/api/v1/mensajes

Permisos (scopes)

Al crear la key elegis que puede hacer. Cada endpoint indica el permiso que exige:

  • leer — consultar mensajes, contactos y plantillas.
  • escribir — registrar mensajes en la bandeja.
  • enviar — mandar WhatsApp reales (respuestas y plantillas).

Las keys pueden tener vencimiento (30/90/365 dias). Una key vencida devuelve 401; sin el permiso necesario, 403.

Limites

120 solicitudes por minuto por API key. Si te pasas, recibis 429 con el header Retry-After (segundos a esperar). Demasiados intentos con keys invalidas bloquean tu IP por 15 minutos.

200 — OK
400 — Datos invalidos
401 — Key invalida o vencida
403 — Sin el permiso necesario
404 — No encontrado
429 — Limite de solicitudes

Endpoints

Webhooks salientes (Wando te avisa a vos)

Ademas de consultarnos por API, Wando puede avisarle a tu sistema cuando pasa algo: configuras una URL en Integraciones del panel (Make, Zapier, n8n o una URL propia), elegis los eventos, y te hacemos un POST con JSON cada vez que ocurren.

Eventos

  • nuevo_mensaje — un cliente te escribio por WhatsApp.
  • mensaje_aprobado — un agente aprobo y envio una respuesta.
  • conversacion_escalada — un mensaje se marco como urgente / necesita un humano.
  • chat_manual — alguien del equipo uso "Enviar a mi sistema" desde el chat (incluye los ultimos 10 mensajes y el link a la conversacion).

Payload

Todos los eventos comparten esta base. sugerencia_ia solo viene en nuevo_mensaje (si la IA ya genero una); conversacion, mensajes y enviado_por solo en chat_manual.

{
  "evento": "nuevo_mensaje",
  "evento_id": "9f1b6c2e-...",          // unico por evento, ESTABLE entre reintentos
  "empresa_id": "uuid",
  "contacto": {
    "nombre": "Juan Perez",
    "telefono": "+5491123456789",
    "email": "juan@mail.com"            // puede ser null
  },
  "mensaje": {
    "texto": "Hola, quiero consultar...",
    "timestamp": "2026-07-07T14:30:00Z"
  },
  "sugerencia_ia": "Hola Juan! ...",    // opcional

  // Solo en chat_manual:
  "conversacion": { "id": "uuid", "link": "https://wando.online/admin?chat=..." },
  "mensajes": [ { "tipo": "Recibido", "texto": "...", "timestamp": "..." } ],
  "enviado_por": "Nombre del agente"
}

Verificar la firma (que venga de Wando de verdad)

Cada POST lleva dos headers: X-Wando-Event (el nombre del evento) y X-Wando-Signature = sha256=<hex>, el HMAC-SHA256 del body crudo calculado con el secret de tu integracion (lo ves en el panel, en Integraciones al editar el webhook). Verificalo asi (Node.js):

const crypto = require('crypto')

function esDeWando(bodyCrudo, headerFirma, secret) {
  const esperada = 'sha256=' +
    crypto.createHmac('sha256', secret).update(bodyCrudo).digest('hex')
  return headerFirma?.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(headerFirma), Buffer.from(esperada))
}

Importante: firma sobre los bytes exactos del body. Si tu framework parsea el JSON antes, usa el raw body (en Express: express.raw() o req.rawBody). La verificacion es opcional pero recomendada si tu URL hace algo sensible.

Reintentos

  • Tu endpoint tiene que responder 2xx en menos de 8 segundos. Cualquier otra cosa (timeout, 4xx, 5xx) cuenta como fallo.
  • Si falla, reintentamos hasta 6 veces con backoff exponencial: ~1, 2, 4, 8, 16 y 30 minutos.
  • Los reintentos mandan el mismo evento_id: si tu sistema ya lo proceso, ignora el duplicado (puede pasar que respondas lento y el envio cuente como fallo).
  • Si desactivas o borras la integracion, los reintentos pendientes se descartan.
  • Excepcion: chat_manual no reintenta — el que lo mando esta mirando y ve el error al instante.

Notas

  • Todos los timestamps estan en formato ISO 8601 (UTC).
  • Los IDs son UUID v4.
  • Las respuestas siempre son JSON con Content-Type: application/json.
  • Ventana de 24hs de WhatsApp: texto libre (/responder) solo se puede enviar si el cliente escribio en las ultimas 24 horas. Fuera de esa ventana, WhatsApp exige plantillas aprobadas (/send-template).
  • El endpoint /api/v1/mensajes/entrante es para testing. No genera sugerencia de IA ni dispara webhooks.
  • El ultimo uso de cada API key se actualiza automaticamente (lo ves en el panel).
  • Wando tambien te avisa a vos: podes configurar webhooks salientes (Make, Zapier, n8n o una URL propia) desde Integraciones en el panel — ver Webhooks salientes arriba.

Wando API v1 — Documentacion generada automaticamente