Instancias

Una instancia representa un número de WhatsApp vinculado. Formato obligatorio: tenantId__clientId__label (solo minúsculas, números, guiones y guiones bajos).

Crear instancia

json

POST /instance/create

{
  "instanceName": "acme__soporte__main",
  "webhookUrl": "https://mi-app.com/webhooks/whatsapp",
  "webhookSecret": "mi-secreto-minimo-16-chars"
}

// Respuesta 201
{ "instanceName": "acme__soporte__main", "status": "close" }

Obtener QR

Decodificá el base64 y mostralo al usuario. El QR expira en ~40 segundos.

json

GET /instance/acme__soporte__main/qr

// Respuesta 200
{ "qrcode": "data:image/png;base64,iVBORw0KGgo..." }
// El QR expira en ~40 segundos. Volver a llamar si venció.

Pairing Code (alternativa al QR)

En lugar de mostrar un QR, podés generar un código de 6 dígitos. El usuario lo ingresa manualmente en WhatsApp → Dispositivos vinculados → Vincular con número de teléfono. Útil para flujos sin interfaz gráfica.

json

POST /instance/acme__soporte__main/pairing-code/request

{ "phoneNumber": "5491112345678" }

// Respuesta 200
{ "pairingCode": "123456" }
// El usuario lo ingresa en WhatsApp → Dispositivos vinculados → Vincular con número

Estado de conexión

Polling recomendado cada 3–5s mientras se espera la conexión.

json

GET /instance/acme__soporte__main/status

// Respuesta 200
{
  "instanceName": "acme__soporte__main",
  "state": "open",
  "phoneNumber": "5491112345678",
  "connectedAt": "2026-03-15T10:00:00.000Z",
  "messagesQueuedCount": 0
}

state	Significado
`close`	No vinculado. Requiere QR o pairing code.
`connecting`	QR escaneado. Esperando confirmación.
`open`	Conectado y listo para enviar mensajes.

Listar instancias del tenant

json

GET /tenant/acme/instances

// Respuesta 200 — array con todas las instancias del tenant
[
  { "instanceName": "acme__soporte__main", "state": "open", "phoneNumber": "5491112345678" },
  { "instanceName": "acme__ventas__main",  "state": "close", "phoneNumber": null }
]

Listar instancias por cliente

Más granular: solo instancias de un clientId específico dentro del tenant.

json

GET /tenant/acme/client/soporte/instances

// Respuesta 200 — solo instancias del cliente "soporte"
[{ "instanceName": "acme__soporte__main", "state": "open" }]

Estado de la cola

json

GET /instance/acme__soporte__main/queue

// Respuesta 200
{ "urgent": 0, "normal": 3, "bulk": 12, "total": 15 }

Eliminar instancia

Desconecta WhatsApp. Los mensajes pendientes en cola se marcan como fallidos.

bash

DELETE /instance/acme__soporte__main

// Respuesta 204 No Content