Listar Instâncias

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"

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 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"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=minha-instancia",
    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=minha-instancia", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

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"

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/instance/list?instanceName=vendas,suporte",
    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=vendas,suporte", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

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"

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)
}

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

string

obrigatório

TokenAccount ou TokenInstance.

Query parameters

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`

Campo	Tipo	Descrição
`state`	string	Estado real da conexão whatsmeow (`connected`, `connecting`, `disconnected`, `loggedout`)
`numberJid`	string \| null	JID do número (`5511999999999@s.whatsapp.net`) ou `null` se nunca conectou
`presenceStatus`	string	`available`, `unavailable`, `composing`…
`displayStatus`	string	Status amigável para UI

`profile`

Campo	Tipo	Descrição
`name`	string	Nome de exibição do WhatsApp
`pictureUrl`	string	URL da foto de perfil (cache do whatsmeow)
`isBusiness`	boolean	`true` se é WhatsApp Business
`businessName`	string	Nome 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ção	Comportamento
TokenAccount sem filtro	Retorna todas da conta
TokenAccount com 1 nome	Retorna aquela específica, ou 404 se não existir
TokenAccount com vários nomes	Retorna as que existirem, nomes inexistentes são ignorados
TokenAccount com filtro só de vírgulas/espaços	Retorna lista vazia sem erro
TokenInstance	Ignora filtro; retorna apenas a própria instância

Erros

HTTP	`error.message`	Quando
401	`Invalid token`	Token ausente ou inválido
404	`Instance not found`	Nome único solicitado não existe
429	`Rate limit exceeded. Try again later.`	Mais de 100 requisições por minuto

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

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.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Listar Instâncias

Descrição

Exemplos

Listar todas as instancias da conta

Filtrar por nome único (recomendado para checar status)

Filtrar várias

Ver dados da própria instância

Resposta de sucesso

Headers

Query parameters

Campos da resposta

`connection`

`profile`

Integrações

Regras do filtro

Erros

Próximo

Criar nova instância

Conectar ao WhatsApp

​Descrição

​Exemplos

​Listar todas as instancias da conta

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

​Filtrar várias

​Ver dados da própria instância

​Resposta de sucesso

​Headers

​Query parameters

​Campos da resposta

​connection

​profile

​Integrações

​Regras do filtro

​Erros

​Próximo

Criar nova instância

Conectar ao WhatsApp

Descrição

Exemplos

Listar todas as instancias da conta

Filtrar por nome único (recomendado para checar status)

Filtrar várias

Ver dados da própria instância

Resposta de sucesso

Headers

Query parameters

Campos da resposta

`connection`

`profile`

Integrações

Regras do filtro

Erros

Próximo