Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

O módulo Instância é o ponto de partida da integração com a RyzeAPI. Cada instância representa uma conexão ativa com um número de WhatsApp, você pode ter várias por conta (uma para vendas, outra para suporte, outra para marketing, por exemplo). Aqui você encontra tudo que precisa para:
  • Provisionar novas instâncias na sua conta, opcionalmente já com webhook, WebSocket e Chatwoot configurados no mesmo request
  • Conectar cada uma a um número via QR code ou pairing code
  • Inspecionar o estado atual e os dados de perfil
  • Configurar proxy, ajustes de comportamento e armazenamento S3
  • Desconectar (logout) mantendo a instância, ou deletar completamente
Status atual de uma instância é consultado via GET /api/instance/list?instanceName=<nome>. A resposta inclui o estado da conexão, perfil, e o resumo das integrações (webhook, websocket, chatwoot).

​
Ciclo de vida típico

1

Criar

POST /api/instance/new provisiona a instância e retorna o TokenInstance. A instância nasce no estado disconnected.
2

Conectar

GET /api/instance/connect/:instance gera o QR code (ou pairing code) para escanear no celular.
3

Verificar

GET /api/instance/list?instanceName=<nome> confirma que o estado virou connected e expõe os dados completos (perfil, integrações, settings).
4

Operar

A instância fica pronta para enviar/receber mensagens, gerenciar grupos, etc. Webhooks e WebSocket avisam mudanças de estado em tempo real.
5

Encerrar

Use logout para desconectar mantendo a instância, ou delete para remover tudo definitivamente.

​
Configuração inline na criação

Os blocos de webhook, WebSocket e Chatwoot podem ser enviados dentro do body de POST /api/instance/new, assim a instância já nasce integrada, sem precisar de chamadas adicionais. Veja a referência completa em Criar instância.

Webhook inline

Campos webhookEnabled, webhookURL, webhookEvents, webhookAuthorization…

WebSocket inline

Campos websocketEnabled, websocketEvents, websocketMediaBase64.

Chatwoot inline

Campos chatwootEnabled, chatwootBaseUrl, chatwootAccountId, chatwootApiToken, chatwootInboxName…

​
Gestão da instância

Criar instância

POST /api/instance/new, provisiona uma nova, já aplicando proxy, webhook, websocket, chatwoot, settings e S3 inline.

Listar instâncias

GET /api/instance/list, todas da sua conta (com TokenAccount) ou só a própria (com TokenInstance). Aceita ?instanceName= para filtrar.

Deletar

DELETE /api/instance/delete/:instance, remove tudo definitivamente.

​
Conexão com WhatsApp

Conectar (QR ou pairing)

GET /api/instance/connect/:instance, gera QR code ou pairing code para vincular o número.

Reconectar

POST /api/instance/reconnect/:instance, reativa uma sessão que caiu, sem precisar de QR novo.

Logout

DELETE /api/instance/logout/:instance, desconecta do WhatsApp mantendo a instância (precisará de QR novo para reconectar).

​
Configuração da instância

Verificar ajustes

GET /api/instance/getSettings/:instance

Atualizar ajustes

POST /api/instance/settings/:instance, auto-rejeitar chamadas, ignorar grupos, manter online, etc.

Verificar proxy

GET /api/instance/getProxy/:instance

Atualizar proxy

POST /api/instance/proxy/:instance, HTTP, HTTPS ou SOCKS5.

Verificar configuração S3

GET /api/instance/getS3/:instance

Atualizar configuração S3

POST /api/instance/s3/:instance, armazenar mídias recebidas em bucket próprio.

​
Estados possíveis de uma instância

EstadoO que significa
disconnectedInstância criada mas sem sessão ativa
connectingAguardando conexão via QrCode ou Pairing Code com o WhatsApp
connectedPronta para enviar e receber
loggedoutUsuário desvinculou no celular ou foi feito logout pela API
bannedConta banida pelo WhatsApp
Para inspecionar o estado atual, use GET /api/instance/list?instanceName=<nome>. A resposta inclui connection.state, connection.numberJid, connection.presenceStatus, connection.displayStatus e o objeto profile (nome, foto, business).

​
Forma do erro

A API retorna sempre o mesmo shape de erro em qualquer endpoint deste módulo: 
{
  "success": false,
  "error": {
    "message": "<descrição acionável>"
  }
}
Não há campo code, use o status HTTP e o texto do error.message para classificar.

​
Boas práticas

Para checar o estado da instância, use GET /api/instance/list?instanceName=<nome> em vez de polling agressivo, webhooks/WebSocket são a forma recomendada para reagir a mudanças.
Monitore eventos instance.state via webhook/WebSocket para reagir a disconnected / loggedout automaticamente.

​
Relacionados

Enviar mensagens

Depois de conectar, comece a enviar.

Configurar webhook

Receba eventos da instância em tempo real.