Volver al panelMarkdown
Documentación pública

API pública

Esta documentación cubre los dos métodos públicos disponibles para integraciones externas: enviar mensajes y escuchar eventos en tiempo real por Socket.IO.

Autenticación: `Authorization: Bearer <apiKey>`.
Enviar mensaje: `POST /api/public/messages/send` con `target`.
Bootstrap realtime: `GET /api/public/socket`.
Conectar realtime: `io({ path: "/api/socketio", auth: { apiKey } })`.
Lectura rápida

La API pública se consume con el header Authorization: Bearer <apiKey>.

El envío de mensajes y el bootstrap realtime son los dos métodos HTTP públicos disponibles.

Después del bootstrap, conecta con socket.io-client usando path: "/api/socketio" y auth.apiKey.

Las rutas devuelven JSON uniforme cuando corresponda, con errores en la forma { "error": "mensaje" }.

Formato de respuestas

Éxito: el envío de mensajes responde con JSON y la conexión realtime devuelve un JSON de bootstrap y luego un evento ready por Socket.IO.

Errores: la API responde con 401 Unauthorized cuando falta o es inválida la API key.

CORS: las rutas públicas aceptan Content-Type y Authorization.

Socket.IO público

La conexión realtime pública se realiza con `io({ path: "/api/socketio", auth: { apiKey } })`. Al autenticarse emite `ready` y sincroniza mensajes entrantes y salientes.

ready

Se emite apenas la API key fue validada correctamente.

Respuesta esperada

{
  "ok": true,
  "sessionId": "session_id"
}

Notas

  • Este evento confirma que el socket público quedó autenticado para la sesión elegida.
message:create

Se emite al persistir un mensaje entrante o saliente. Incluye el nombre y el teléfono del remitente cuando están disponibles.

Respuesta esperada

{
  "id": "message_id",
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "sender": "them",
  "senderName": "Maria",
  "senderPhone": "+595987654321",
  "text": "Hola",
  "sentAt": "2026-04-17T00:00:00.000Z"
}

Notas

  • El campo `senderPhone` se agrega para identificar el remitente desde el evento Socket.IO.
  • Cuando el mensaje pertenece a un grupo, `chatId` puede terminar en `@g.us` y debe reutilizarse como `target` al responder.
message:update

Se emite cuando cambia el estado, contenido o metadata de un mensaje ya persistido.

Respuesta esperada

{
  "id": "message_id",
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "deliveryStatus": "read"
}
chat:update

Se emite cuando cambia el resumen del chat, incluyendo último mensaje y no leídos.

Respuesta esperada

{
  "sessionId": "session_id",
  "chat": {
    "id": "12345@c.us",
    "name": "Maria",
    "unreadCount": 1
  }
}
message:delete

Se emite cuando un mensaje se elimina para mí o para todos.

Respuesta esperada

{
  "sessionId": "session_id",
  "chatId": "12345@c.us",
  "messageId": "message_id",
  "scope": "everyone"
}

Métodos públicos

La API pública expone exactamente dos métodos HTTP: uno para enviar mensajes y otro para preparar la conexión realtime pública.

POSTPúblico

/api/public/messages/send

Envía un mensaje desde una integración externa a un número o chatId.

Cabeceras

  • Authorization: Bearer <apiKey>
  • Content-Type: application/json

Body

{
  "target": "string",
  "message": "string"
}

Respuesta esperada

{
  "ok": true,
  "message": {
    "id": "message_id",
    "chatId": "12345@c.us"
  }
}

Notas

  • La API key debe pertenecer a la sesión elegida.
  • Para responder a grupos, reutiliza el `chatId` recibido en eventos como `message:create` y envíalo como `target`.
GETPúblico

/api/public/socket

Valida la API key y deja listo el servidor Socket.IO público.

Cabeceras

  • Authorization: Bearer <apiKey>

Respuesta esperada

{
  "ok": true,
  "sessionId": "session_id"
}

Notas

  • Luego conecta con `socket.io-client` usando `path: "/api/socketio"` y `auth.apiKey`.
  • El canal realtime emite `ready` al autenticar y sincroniza mensajes entrantes y salientes.

Errores de la API pública

Cuando el body no pasa la validación, la API devuelve 400 con un JSON que describe el problema.

En general, el cuerpo de error usa la forma { "error": "..." }.

Si la API key no coincide con ninguna sesión válida, el backend responde con 401.

Sugerencia de implementación

Para consumir la API pública, envía siempre el header Authorization en el bootstrap y el Content-Type correcto en los requests con body.

Para escuchar mensajes entrantes, conecta el socket con la misma API key en auth.apiKey.

Si quieres reutilizar esta guía en otras automatizaciones, abre la versión Markdown de /tutorial.md.

Abrir versión Markdown