Saltar al contenido principal
GET
/
api
/
instance
/
list
Listar instancias
curl --request GET \
  --url https://api.example.com/api/instance/list \
  --header 'token: <token>'
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: sí

​
Descripción

Cada item devuelto incluye el status actual, estado de conexión, datos de perfil y un resumen de las integraciones (webhook, websocket, chatwoot, proxy, settings, s3). Esta es la forma recomendada de inspeccionar el estado de una instancia. El resultado depende del tipo de token:
  • TokenAccount, devuelve todas las instancias de tu cuenta. Acepta el filtro ?instanceName=.
  • TokenInstance, devuelve solo la instancia dueña del token (el filtro se ignora).

​
Ejemplos

​
Listar todas las instancias de la cuenta

Sin filtro y usando el TokenAccount, devuelve todas las instancias visibles para la cuenta con status, perfil y resumen de integraciones de cada una. 
curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Account"

​
Filtrar por un nombre (recomendado para verificación de status)

Pasando ?instanceName=my-instance, devuelve solo esa instancia, o 404 si no existe. Forma más económica de hacer polling al estado de la conexión después de llamar a /connect. 
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=my-instance" \
  -H "token: $Token_Account"

​
Filtrar varios

Acepta múltiples nombres separados por coma en ?instanceName=sales,support. Los nombres no existentes se ignoran silenciosamente, solo devuelve 404 cuando el filtro tiene un único nombre y este no existe. 
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=sales,support" \
  -H "token: $Token_Account"

​
Ver datos de la propia instancia

Usando el TokenInstance, cualquier filtro se ignora y la respuesta trae solo la instancia dueña del token. Escenario típico para clientes que solo conocen el token de la instancia y quieren inspeccionar su propio estado. 
curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Instance"

​
Respuesta exitosa

200 OK
{
  "success": true,
  "message": "1 Instance found",
  "instances": [
    {
      "id": "5e1d...",
      "name": "my-instance",
      "token": "a1b2c3d4-...",
      "status": "connected",
      "connection": {
        "state": "connected",
        "numberJid": "5511999999999@s.whatsapp.net",
        "presenceStatus": "available",
        "displayStatus": "Active"
      },
      "profile": {
        "name": "Orion",
        "pictureUrl": "https://pps.whatsapp.net/...",
        "isBusiness": false,
        "businessName": ""
      },
      "proxy": {
        "enabled": false,
        "host": null,
        "port": null,
        "protocol": null,
        "username": null,
        "password": null
      },
      "webhook": {
        "enabled": true,
        "url": "https://myapp.com/webhook",
        "events": ["message.exchange"]
      },
      "websocket": {
        "enabled": true,
        "events": ["message.exchange"],
        "mediaBase64": false
      },
      "chatwoot": {
        "enabled": true,
        "status": "active",
        "bridgeIntegrationId": "int_xyz789abc",
        "baseUrl": "https://chatwoot.example.com",
        "accountId": 5,
        "inboxName": "WhatsApp - Orion",
        "apiToken": "sk_live_abc123...",
        "signMessages": true,
        "ignoreGroups": false,
        "startAsPending": false,
        "reopenResolved": true
      },
      "settings": {
        "autoRejectCalls": false,
        "callRejectMessage": "",
        "ignoreGroupMessages": false,
        "keepOnlineStatus": false,
        "autoReadMessages": false,
        "disableHistorySync": true,
        "ignoreStatus": false
      },
      "s3": {
        "enabled": false,
        "region": null,
        "bucket": null,
        "accessKey": null,
        "secretKey": null,
        "endpoint": null,
        "pathPrefix": null
      },
      "createdAt": "2026-04-28T10:30:00Z",
      "updatedAt": "2026-04-28T10:35:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}
El campo message varía: "1 Instance found" cuando el total es 1, y "<N> Instances found" para otros valores.

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.

​
Parámetros de consulta

​
instanceName
string
Filtra por nombre. Acepta uno o varios nombres separados por coma (p. ej., ?instanceName=sales,support). Solo funciona con TokenAccount.

​
Campos de respuesta

​
connection

CampoTipoDescripción
statestringEstado real de la conexión whatsmeow (connected, connecting, disconnected, loggedout)
numberJidstring | nullJID del número (5511999999999@s.whatsapp.net) o null si nunca se conectó
presenceStatusstringavailable, unavailable, composing…
displayStatusstringStatus amigable para UI

​
profile

CampoTipoDescripción
namestringNombre de display de WhatsApp
pictureUrlstringURL de la foto de perfil (cache de whatsmeow)
isBusinessbooleantrue si es WhatsApp Business
businessNamestringNombre del Business (vacío si no es Business)

​
Integraciones

  • webhook, webhook por defecto (label default). enabled: false significa sin webhook.
  • websocket, { enabled, events, mediaBase64 }. enabled: false significa que el WebSocket está apagado para la instancia.
  • chatwoot, { enabled, status, bridgeIntegrationId, baseUrl, accountId, inboxName, apiToken, signMessages, ignoreGroups, startAsPending, reopenResolved }. enabled: false significa que no hay integración Chatwoot activa (o que el módulo Chatwoot no está habilitado en el servidor). El apiToken viene en plaintext (misma exposición intencional que GET /api/chatwoot/list/:instance), trátalo como sensible y solo aparece cuando hay integración. Los cuatro flags se devuelven siempre como true/false (las instancias sin Chatwoot reportan todos en false junto con enabled: false).
  • proxy, proxy individual (no incluye el global del deploy).
  • settings, flags de comportamiento (consulta Actualizar settings).
  • s3, configuración individual de almacenamiento S3.

​
Reglas de filtrado

SituaciónComportamiento
TokenAccount sin filtroDevuelve todas las de la cuenta
TokenAccount con 1 nombreDevuelve esa específica, o 404 si no existe
TokenAccount con varios nombresDevuelve las que existen, los nombres inexistentes se ignoran
TokenAccount con filtro de solo comas/espaciosDevuelve lista vacía sin error
TokenInstanceIgnora el filtro; devuelve solo su propia instancia

​
Errores

HTTPerror.messageCuándo
401Invalid tokenToken faltante o inválido
404Instance not foundÚnico nombre solicitado no existe
429Rate limit exceeded. Try again later.Más de 100 solicitudes por minuto
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Siguiente

Crear nueva instancia

Aprovisiona una más en tu cuenta, ya con webhook, websocket y chatwoot configurados inline si lo deseas.

Conectar a WhatsApp

Genera el QR code o pairing code para vincular el número.