Pular para o conteúdo principal
GET
/
api
/
instance
/
list
Listar Instâncias
curl --request GET \
  --url https://api.example.com/api/instance/list \
  --header 'token: <token>'
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

​
Descrição

Cada item retornado inclui o status atual, o estado da conexão, dados de perfil e o resumo das integrações (webhook, websocket, chatwoot, proxy, settings, s3). Esta é a forma recomendada para inspecionar o estado de uma instância. O resultado depende do tipo de token:
  • TokenAccount, retorna todas as instâncias da sua conta. Aceita filtro ?instanceName=.
  • TokenInstance, retorna apenas a própria instância do token (filtro é ignorado).

​
Exemplos

​
Listar todas as instancias da conta

Sem filtro e usando o TokenAccount, devolve todas as instâncias visíveis para a conta com status, perfil e resumo das integrações de cada uma. 
curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Account"

​
Filtrar por nome único (recomendado para checar status)

Passando ?instanceName=minha-instancia, retorna apenas aquela instância, ou 404 se não existir. Forma mais barata para fazer poll do estado de conexão após chamar /connect. 
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=minha-instancia" \
  -H "token: $Token_Account"

​
Filtrar várias

Aceita múltiplos nomes separados por vírgula em ?instanceName=vendas,suporte. Nomes inexistentes são ignorados silenciosamente, só dá 404 quando o filtro tem um único nome e ele não existe. 
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=vendas,suporte" \
  -H "token: $Token_Account"

​
Ver dados da própria instância

Usando o TokenInstance, qualquer filtro é ignorado e a resposta traz somente a instância dona do token. Cenário típico para clientes que só conhecem o token instance e querem inspecionar o próprio estado. 
curl -X GET "https://ryzeapi.cloud/api/instance/list" \
  -H "token: $Token_Instance"

​
Resposta de sucesso

200 OK
{
  "success": true,
  "message": "1 Instance found",
  "instances": [
    {
      "id": "5e1d...",
      "name": "minha-instancia",
      "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://meuapp.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
  }
}
O campo message varia: "1 Instance found" quando o total é 1, e "<N> Instances found" para outros valores.

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.

​
Query parameters

​
instanceName
string
Filtra por nome. Aceita um ou mais nomes separados por vírgula (ex.: ?instanceName=vendas,suporte). Funciona apenas com TokenAccount.

​
Campos da resposta

​
connection

CampoTipoDescrição
statestringEstado real da conexão whatsmeow (connected, connecting, disconnected, loggedout)
numberJidstring | nullJID do número (5511999999999@s.whatsapp.net) ou null se nunca conectou
presenceStatusstringavailable, unavailable, composing…
displayStatusstringStatus amigável para UI

​
profile

CampoTipoDescrição
namestringNome de exibição do WhatsApp
pictureUrlstringURL da foto de perfil (cache do whatsmeow)
isBusinessbooleantrue se é WhatsApp Business
businessNamestringNome comercial (vazio se não for Business)

​
Integrações

  • webhook, webhook default (label default). enabled: false significa sem webhook.
  • websocket, { enabled, events, mediaBase64 }. enabled: false significa que o WebSocket está desligado para a instância.
  • chatwoot, { enabled, status, bridgeIntegrationId, baseUrl, accountId, inboxName, apiToken, signMessages, ignoreGroups, startAsPending, reopenResolved }. enabled: false significa sem integração Chatwoot ligada (ou módulo Chatwoot não habilitado no servidor). O apiToken vem em plaintext (mesma exposição intencional do GET /api/chatwoot/list/:instance), trate como sensível e só aparece quando há integração. Os quatro flags são sempre retornados como true/false (instâncias sem Chatwoot reportam todos false junto de enabled: false).
  • proxy, proxy individual (não inclui o global do deploy).
  • settings, flags de comportamento (ver Atualizar settings).
  • s3, config de storage S3 individual.

​
Regras do filtro

SituaçãoComportamento
TokenAccount sem filtroRetorna todas da conta
TokenAccount com 1 nomeRetorna aquela específica, ou 404 se não existir
TokenAccount com vários nomesRetorna as que existirem, nomes inexistentes são ignorados
TokenAccount com filtro só de vírgulas/espaçosRetorna lista vazia sem erro
TokenInstanceIgnora filtro; retorna apenas a própria instância

​
Erros

HTTPerror.messageQuando
401Invalid tokenToken ausente ou inválido
404Instance not foundNome único solicitado não existe
429Rate limit exceeded. Try again later.Mais de 100 requisições por minuto
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Próximo

Criar nova instância

Provisiona mais uma na sua conta, já com webhook, websocket e chatwoot configurados inline se quiser.

Conectar ao WhatsApp

Gere o QR code ou pairing code para vincular o número.