> ## 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.

# Visão Geral

> Ciclo de vida das suas conexões com o WhatsApp: criar, conectar, configurar e remover

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

<Info>
  **Status atual de uma instância** é consultado via [`GET /api/instance/list?instanceName=<nome>`](/pt/api/instance/list). A resposta inclui o estado da conexão, perfil, e o resumo das integrações (webhook, websocket, chatwoot).
</Info>

## Ciclo de vida típico

<Steps>
  <Step title="Criar">
    [`POST /api/instance/new`](/pt/api/instance/create) provisiona a instância e retorna o **TokenInstance**. A instância nasce no estado `disconnected`.
  </Step>

  <Step title="Conectar">
    [`GET /api/instance/connect/:instance`](/pt/api/instance/connect) gera o QR code (ou pairing code) para escanear no celular.
  </Step>

  <Step title="Verificar">
    [`GET /api/instance/list?instanceName=<nome>`](/pt/api/instance/list) confirma que o estado virou `connected` e expõe os dados completos (perfil, integrações, settings).
  </Step>

  <Step title="Operar">
    A instância fica pronta para enviar/receber mensagens, gerenciar grupos, etc. Webhooks e WebSocket avisam mudanças de estado em tempo real.
  </Step>

  <Step title="Encerrar">
    Use [`logout`](/pt/api/instance/logout) para desconectar mantendo a instância, ou [`delete`](/pt/api/instance/delete) para remover tudo definitivamente.
  </Step>
</Steps>

## Configuração inline na criação

<Tip>
  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](/pt/api/instance/create).
</Tip>

<CardGroup cols={3}>
  <Card title="Webhook inline" href="/pt/api/instance/create">
    Campos `webhookEnabled`, `webhookURL`, `webhookEvents`, `webhookAuthorization`...
  </Card>

  <Card title="WebSocket inline" href="/pt/api/instance/create">
    Campos `websocketEnabled`, `websocketEvents`, `websocketMediaBase64`.
  </Card>

  <Card title="Chatwoot inline" href="/pt/api/instance/create">
    Campos `chatwootEnabled`, `chatwootBaseUrl`, `chatwootAccountId`, `chatwootApiToken`, `chatwootInboxName`...
  </Card>
</CardGroup>

## Gestão da instância

<CardGroup cols={2}>
  <Card title="Criar instância" href="/pt/api/instance/create">
    `POST /api/instance/new`, provisiona uma nova, já aplicando proxy, webhook, websocket, chatwoot, settings e S3 inline.
  </Card>

  <Card title="Listar instâncias" href="/pt/api/instance/list">
    `GET /api/instance/list`, todas da sua conta (com TokenAccount) ou só a própria (com TokenInstance). Aceita `?instanceName=` para filtrar.
  </Card>

  <Card title="Deletar" href="/pt/api/instance/delete">
    `DELETE /api/instance/delete/:instance`, remove tudo definitivamente.
  </Card>
</CardGroup>

## Conexão com WhatsApp

<CardGroup cols={2}>
  <Card title="Conectar (QR ou pairing)" href="/pt/api/instance/connect">
    `GET /api/instance/connect/:instance`, gera QR code ou pairing code para vincular o número.
  </Card>

  <Card title="Reconectar" href="/pt/api/instance/reconnect">
    `POST /api/instance/reconnect/:instance`, reativa uma sessão que caiu, sem precisar de QR novo.
  </Card>

  <Card title="Logout" href="/pt/api/instance/logout">
    `DELETE /api/instance/logout/:instance`, desconecta do WhatsApp mantendo a instância (precisará de QR novo para reconectar).
  </Card>
</CardGroup>

## Configuração da instância

<CardGroup cols={2}>
  <Card title="Verificar ajustes" href="/pt/api/instance/settings-read">
    `GET /api/instance/getSettings/:instance`
  </Card>

  <Card title="Atualizar ajustes" href="/pt/api/instance/settings-update">
    `POST /api/instance/settings/:instance`, auto-rejeitar chamadas, ignorar grupos, manter online, etc.
  </Card>

  <Card title="Verificar proxy" href="/pt/api/instance/proxy-read">
    `GET /api/instance/getProxy/:instance`
  </Card>

  <Card title="Atualizar proxy" href="/pt/api/instance/proxy-update">
    `POST /api/instance/proxy/:instance`, HTTP, HTTPS ou SOCKS5.
  </Card>

  <Card title="Verificar configuração S3" href="/pt/api/instance/s3-read">
    `GET /api/instance/getS3/:instance`
  </Card>

  <Card title="Atualizar configuração S3" href="/pt/api/instance/s3-update">
    `POST /api/instance/s3/:instance`, armazenar mídias recebidas em bucket próprio.
  </Card>
</CardGroup>

## Estados possíveis de uma instância

| Estado         | O que significa                                              |
| -------------- | ------------------------------------------------------------ |
| `disconnected` | Instância criada mas sem sessão ativa                        |
| `connecting`   | Aguardando conexão via QrCode ou Pairing Code com o WhatsApp |
| `connected`    | Pronta para enviar e receber                                 |
| `loggedout`    | Usuário desvinculou no celular ou foi feito logout pela API  |
| `banned`       | Conta banida pelo WhatsApp                                   |

<Info>
  Para inspecionar o estado atual, use [`GET /api/instance/list?instanceName=<nome>`](/pt/api/instance/list). A resposta inclui `connection.state`, `connection.numberJid`, `connection.presenceStatus`, `connection.displayStatus` e o objeto `profile` (nome, foto, business).
</Info>

## Forma do erro

A API retorna sempre o mesmo shape de erro em qualquer endpoint deste módulo:

```json theme={null}
{
  "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

<Check>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.</Check>
<Check>Monitore eventos `instance.state` via webhook/WebSocket para reagir a `disconnected` / `loggedout` automaticamente.</Check>

## Relacionados

<CardGroup cols={2}>
  <Card title="Enviar mensagens" icon="paper-plane" href="/pt/api/messages/overview">
    Depois de conectar, comece a enviar.
  </Card>

  <Card title="Configurar webhook" icon="webhook" href="/pt/api/events/overview">
    Receba eventos da instância em tempo real.
  </Card>
</CardGroup>