API y webhooks

SWS Atiende se integra con tus sistemas en dos direcciones. Con la API tus programas envían mensajes de WhatsApp o consultan tickets y contactos. Con los webhooks la plataforma avisa a tu sistema cada vez que ocurre algo: un ticket nuevo, un mensaje recibido, un contacto creado.

Este capítulo está pensado para la persona técnica de tu empresa. La referencia completa, con ejemplos para copiar y una colección de Postman, está dentro de la app en Herramientas → Documentación de la API.

Enviar mensajes desde tus sistemas

La forma más simple de integrar es el envío de mensajes con el token de la conexión. No requiere usuario ni contraseña: cada número de WhatsApp conectado tiene su propio token.

Obtener el token

1. Entra a Administración → Conexiones y edita la conexión.
2. Copia el valor del campo Token. Si está vacío, escribe uno propio, largo y difícil de adivinar, y guarda.
3. Trata ese token como una contraseña: quien lo tenga puede enviar mensajes con tu número.

Mensaje de texto

POST https://api.swsperu.cloud/api/messages/send
Authorization: Bearer TOKEN_DE_LA_CONEXION
Content-Type: application/json

{
  "number": "51987654321",
  "body": "Hola, tu pedido 1024 ya fue despachado.",
  "userId": "",
  "queueId": ""
}

Campo	Obligatorio	Descripción
number	Sí	Número con código de país y sin signos: 51 + 9 dígitos para Perú.
body	Sí	Texto del mensaje. Acepta saltos de línea y emojis.
userId	No	Id del agente al que se asigna el ticket que se crea o reabre.
queueId	No	Id del departamento en el que cae el ticket.

Respuesta exitosa: código 200 con el mensaje creado. Si la conexión no está conectada responde 400 y si el token no existe responde 401.

Mensaje con archivo

Para enviar una imagen, PDF, audio o video, usa multipart/form-data con el archivo en el campo medias y el texto en body:

curl -X POST https://api.swsperu.cloud/api/messages/send \
  -H "Authorization: Bearer TOKEN_DE_LA_CONEXION" \
  -F "number=51987654321" \
  -F "body=Adjunto tu comprobante" \
  -F "medias=@comprobante.pdf"

Verificar si un número tiene WhatsApp

POST https://api.swsperu.cloud/api/messages/checkNumber
Authorization: Bearer TOKEN_DE_LA_CONEXION
Content-Type: application/json

{ "number": "51987654321" }

Útil antes de una campaña o al registrar un cliente: evita enviar a números inexistentes, que es una de las causas de bloqueo del número.

Buenas prácticas de envío. WhatsApp bloquea números que envían muchos mensajes a contactos que no responden o que los marcan como spam. Envía solo a clientes que esperan tu mensaje, varía el texto, no superes unas decenas de mensajes por minuto y usa la función de campañas, que ya espacia los envíos.

API completa con usuario

Para consultar y modificar tickets, contactos, departamentos y más, la API usa el mismo inicio de sesión que la app. Primero obtienes un token de acceso:

POST https://api.swsperu.cloud/auth/login
Content-Type: application/json

{ "email": "integracion@tuempresa.com", "password": "********" }

La respuesta trae token, que se envía en cada petición como Authorization: Bearer <token>, y una cookie de refresco para POST /auth/refresh cuando expira. Recomendamos crear un usuario exclusivo para la integración, con perfil de usuario y solo los departamentos necesarios.

Los recursos principales son:

Recurso	Operaciones
/tickets	Listar con filtros, ver uno, crear, actualizar estado, agente o departamento.
/messages/:ticketId	Historial de un ticket. POST /messages/send envía con el usuario autenticado.
/contacts	Listar, buscar, crear y editar contactos.
/queue	Departamentos de la empresa.
/users	Agentes de la empresa.
/company-webhooks	Webhooks salientes (ver abajo).

Cada endpoint, con sus parámetros y respuestas, está en Herramientas → Documentación de la API dentro de la app.

Webhooks: recibir eventos en tu sistema

Un webhook es una URL de tu sistema a la que SWS Atiende envía una petición POST con un JSON cada vez que ocurre un evento. Con esto puedes, por ejemplo, registrar en tu CRM cada contacto nuevo, avisar a tu ERP cuando un cliente escribe, o encadenar automatizaciones en n8n, Make o Zapier.

Crear un webhook

1. Entra a Administración → Webhooks y pulsa Nuevo.
2. Indica un nombre, la URL de tu sistema (debe ser https:// y pública) y, opcionalmente, un secreto para firmar los envíos.
3. Marca los eventos que quieres recibir y guarda.
4. Usa el botón Probar para enviar un evento de prueba y ver la respuesta de tu servidor sin esperar un evento real.

La lista muestra, para cada webhook, el estado de la última entrega: código HTTP, fecha y error si lo hubo.

Eventos disponibles

Evento	Cuándo se envía	Datos principales
ticket:create	Se abre un ticket, por un cliente o por un agente.	id, estado, contacto, departamento, agente, conexión.
ticket:update	Cambia el estado, el agente o el departamento.	id, estado, agente, departamento.
message:create	Entra o sale un mensaje.	id, texto, fromMe, tipo y URL del archivo, ticket, contacto.
message:ack	WhatsApp confirma entrega o lectura.	id del mensaje y nuevo ack (1 enviado, 2 entregado, 3 leído).
contact:create	Se registra un contacto nuevo.	id, nombre, número, correo.
whatsapp:ready	Una conexión queda en línea.	id y nombre de la conexión.
whatsapp:qrcode	Una conexión pide escanear el código QR.	id y nombre de la conexión.

Formato del envío

{
  "event": "message:create",
  "timestamp": "2026-10-28T15:04:05.000Z",
  "companyId": 2,
  "data": {
    "id": 10658,
    "body": "Buenas tardes, ¿tienen stock?",
    "fromMe": false,
    "mediaType": null,
    "mediaUrl": null,
    "ticketId": 44,
    "contactId": 318,
    "ack": 0,
    "read": false,
    "createdAt": "2026-10-28T15:04:04.812Z"
  }
}

Cabeceras de cada petición:

Cabecera	Contenido
X-SWSAtiende-Event	Nombre del evento.
X-SWSAtiende-Delivery	Identificador único del envío; sirve para descartar duplicados.
X-SWSAtiende-Signature	Firma sha256=<hex> del cuerpo, solo si configuraste un secreto.

Reintentos

Tu servidor debe responder con un código 2xx en menos de 10 segundos. Si responde 5xx o no responde, SWS Atiende reintenta a los 1, 5 y 30 segundos. Un 4xx se considera rechazo definitivo y no se reintenta. Procesa el evento después de responder, no antes, para no agotar el tiempo.

Verificar la firma

Con un secreto configurado, verifica que el envío realmente viene de SWS Atiende calculando el HMAC SHA-256 del cuerpo sin modificar:

const crypto = require("crypto");

function firmaValida(req, secreto) {
  const esperada = "sha256=" + crypto.createHmac("sha256", secreto)
    .update(req.rawBody) // el cuerpo tal cual llegó, antes de parsear el JSON
    .digest("hex");
  const recibida = req.get("X-SWSAtiende-Signature") || "";
  return recibida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recibida), Buffer.from(esperada));
}

En Express, conserva el cuerpo crudo con express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }).

Preguntas frecuentes

¿Puedo tener varios webhooks? Sí, sin límite práctico. Cada uno elige sus propios eventos.

¿Los webhooks envían el contenido de los archivos? No, envían la URL pública del archivo en mediaUrl; descárgalo desde tu sistema si lo necesitas.

¿Qué pasa si mi servidor está caído? Tras los tres reintentos el evento se descarta y la lista de webhooks muestra el error. Los eventos no se encolan de forma indefinida, así que apóyate en la API para reconciliar si estuviste fuera de línea.

¿La API tiene límite de peticiones? Existe un limitador general para proteger el servidor. Para integraciones intensivas, consúltanos antes para dimensionar tu plan.