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

> Referência completa dos endpoints da RyzeAPI, organizados por módulo

Esta é a referência completa da API. Os endpoints estão organizados em **módulos**, onde cada um cobre um aspecto específico do WhatsApp.

Se você está começando, a leitura recomendada é: [Início rápido](/pt/guide/quickstart) → [Conceitos](/pt/guide/concepts) → [Autenticação](/pt/guide/authentication) antes de mergulhar em um módulo específico.

## URL base e convenções

* **Base URL:** `https://ryzeapi.cloud`
* **Path prefix:** todos os endpoints começam com `/api/<módulo>/...`
* **Probe de saúde:** `/health` (sem prefixo `/api/`)
* **Eventos em tempo real:** `/ws/:instance` (WebSocket)
* **Content-Type:** `application/json` em todo `POST` / `PUT` / `DELETE` com body
* **Autenticação:** header `token` em todas as rotas (veja [Autenticação](/pt/guide/authentication))
* **Rate limit:** `100 req/min` por padrão; criação de instância tem limite estrito de `20 req/min`
* **Body máximo:** 64 MB por requisição (cobre uploads em base64)

## Módulos

<CardGroup cols={2}>
  <Card title="Instância" icon="server" href="/pt/api/instance/overview">
    Criar, conectar, configurar e operar suas instâncias de WhatsApp.
  </Card>

  <Card title="Mensagens" icon="message" href="/pt/api/messages/overview">
    Texto, mídia, sticker, localização, contato, reação, enquete, carrossel, botões, lista, formulário, PIX e status.
  </Card>

  <Card title="Chat" icon="comments" href="/pt/api/chat/overview">
    Contatos, etiquetas, arquivar, fixar, mute, presença, histórico, encaminhar, editar, apagar e mais.
  </Card>

  <Card title="Grupos" icon="users" href="/pt/api/groups/overview">
    Criar grupos, gerenciar participantes, links de convite e moderação.
  </Card>

  <Card title="Comunidades" icon="building" href="/pt/api/communities/overview">
    Criar comunidades e vincular subgrupos.
  </Card>

  <Card title="Newsletter" icon="newspaper" href="/pt/api/newsletter/overview">
    Criar canais (channels) e gerenciar inscrições.
  </Card>

  <Card title="Perfil" icon="user" href="/pt/api/profile/overview">
    Nome, foto, recado e privacidade da conta WhatsApp conectada.
  </Card>

  <Card title="Eventos" icon="webhook" href="/pt/api/events/overview">
    Webhooks (com fila persistida + retry) e WebSockets em tempo real.
  </Card>

  <Card title="WebSocket" icon="plug" href="/pt/api/websocket">
    Upgrade `/ws/:instance`, protocolo, heartbeat, reconexão.
  </Card>

  <Card title="Chatwoot" icon="headset" href="/pt/api/chatwoot/overview">
    Integração nativa com o Chatwoot.
  </Card>

  <Card title="Observabilidade" icon="heart-pulse" href="/pt/api/observability/overview">
    `/health`, probe combinado para orquestradores.
  </Card>
</CardGroup>

## Formato das respostas

Toda chamada retorna um JSON com o campo `success` indicando o resultado:

<Tabs>
  <Tab title="Sucesso">
    ```json theme={null}
    {
      "success": true,
      "message": "Message sent successfully",
      "status": "sent",
      "data": { "...": "..." }
    }
    ```
  </Tab>

  <Tab title="Erro">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "message": "Instance is not connected to WhatsApp"
      }
    }
    ```
  </Tab>
</Tabs>

O envelope de erro tem **apenas** `success` + `error.message`, não existe campo `code` numérico. A diferenciação programática usa o **status HTTP** + texto da mensagem. Veja [Tipos de erro](/pt/guide/errors) para o catálogo completo de mensagens.

## Identificadores WhatsApp (JIDs)

| Tipo               | Formato                  | Exemplo                         |
| ------------------ | ------------------------ | ------------------------------- |
| Privado            | `<phone>@s.whatsapp.net` | `5511999999999@s.whatsapp.net`  |
| Grupo              | `<id>@g.us`              | `120363406289005073@g.us`       |
| Newsletter         | `<id>@newsletter`        | `120363422585881117@newsletter` |
| LID (oculto)       | `<id>@lid`               | `199789077627112@lid`           |
| Broadcast (status) | `status@broadcast`       | `status@broadcast`              |

A maioria dos endpoints aceita **número simples** (`5511999999999`) e converte internamente. Para números brasileiros (com prefixo `55`), a API tenta variações com/sem o "9" extra após o DDD.

## Glossário rápido

* **JID**, identificador único no WhatsApp (contato, grupo, canal, LID).
* **Conta**, seu espaço na RyzeAPI, identificado pelo TokenAccount.
* **Instância**, uma conexão ativa com um número de WhatsApp.
* **TokenAccount**, token de conta; usado para criar/listar/deletar instâncias e operar qualquer instância da conta.
* **TokenInstance**, token específico de uma instância; usado nas operações do dia a dia daquela instância.
* **Webhook**, `POST` que a API faz para sua URL quando um evento acontece (com retry exponencial e DLQ).
* **WebSocket**, conexão persistente para receber eventos em tempo real.
* **Integração Chatwoot**, recurso nativo da RyzeAPI que conecta suas instâncias ao Chatwoot.

## Variáveis em exemplos

A Base URL é sempre `https://ryzeapi.cloud`. Os exemplos usam estas variáveis:

| Variável          | Significado                               |
| ----------------- | ----------------------------------------- |
| `$Token_Account`  | Seu TokenAccount                          |
| `$Token_Instance` | TokenInstance de uma instância específica |
| `$Instance_Name`  | Nome da instância (ex.: `minhaInstancia`) |