Listar instancias

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"

await fetch("https://ryzeapi.cloud/api/instance/list", {
  method: "GET",
  headers: {
    "token": process.env.Token_Account
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list",
    headers={
        "token": os.environ["Token_Account"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/list", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

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"

await fetch("https://ryzeapi.cloud/api/instance/list?instanceName=my-instance", {
  method: "GET",
  headers: {
    "token": process.env.Token_Account
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=my-instance",
    headers={
        "token": os.environ["Token_Account"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/list?instanceName=my-instance", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

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"

await fetch("https://ryzeapi.cloud/api/instance/list?instanceName=sales,support", {
  method: "GET",
  headers: {
    "token": process.env.Token_Account
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=sales,support",
    headers={
        "token": os.environ["Token_Account"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/list?instanceName=sales,support", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

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"

await fetch("https://ryzeapi.cloud/api/instance/list", {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list",
    headers={
        "token": os.environ["Token_Instance"]
    }
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/list", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

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

string

requerido

TokenAccount o TokenInstance.

Parámetros de consulta

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`

Campo	Tipo	Descripción
`state`	string	Estado real de la conexión whatsmeow (`connected`, `connecting`, `disconnected`, `loggedout`)
`numberJid`	string \| null	JID del número (`5511999999999@s.whatsapp.net`) o `null` si nunca se conectó
`presenceStatus`	string	`available`, `unavailable`, `composing`…
`displayStatus`	string	Status amigable para UI

`profile`

Campo	Tipo	Descripción
`name`	string	Nombre de display de WhatsApp
`pictureUrl`	string	URL de la foto de perfil (cache de whatsmeow)
`isBusiness`	boolean	`true` si es WhatsApp Business
`businessName`	string	Nombre 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ón	Comportamiento
TokenAccount sin filtro	Devuelve todas las de la cuenta
TokenAccount con 1 nombre	Devuelve esa específica, o 404 si no existe
TokenAccount con varios nombres	Devuelve las que existen, los nombres inexistentes se ignoran
TokenAccount con filtro de solo comas/espacios	Devuelve lista vacía sin error
TokenInstance	Ignora el filtro; devuelve solo su propia instancia

Errores

HTTP	`error.message`	Cuándo
401	`Invalid token`	Token faltante o inválido
404	`Instance not found`	Único nombre solicitado no existe
429	`Rate limit exceeded. Try again later.`	Más de 100 solicitudes por minuto

{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

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.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Listar instancias

Descripción

Ejemplos

Listar todas las instancias de la cuenta

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

Filtrar varios

Ver datos de la propia instancia

Respuesta exitosa

Cabeceras

Parámetros de consulta

Campos de respuesta

`connection`

`profile`

Integraciones

Reglas de filtrado

Errores

Siguiente

Crear nueva instancia

Conectar a WhatsApp

​Descripción

​Ejemplos

​Listar todas las instancias de la cuenta

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

​Filtrar varios

​Ver datos de la propia instancia

​Respuesta exitosa

​Cabeceras

​Parámetros de consulta

​Campos de respuesta

​connection

​profile

​Integraciones

​Reglas de filtrado

​Errores

​Siguiente

Crear nueva instancia

Conectar a WhatsApp

Descripción

Ejemplos

Listar todas las instancias de la cuenta

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

Filtrar varios

Ver datos de la propia instancia

Respuesta exitosa

Cabeceras

Parámetros de consulta

Campos de respuesta

`connection`

`profile`

Integraciones

Reglas de filtrado

Errores

Siguiente