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

# Conceitos

> Glossário e modelo mental para trabalhar com a RyzeAPI

Entender estes conceitos centrais evita horas de debug. Leia antes de abrir qualquer módulo.

## Conta (Account)

A sua **conta** na RyzeAPI é o que agrupa todas as suas instâncias de WhatsApp. Ela tem:

* Um **TokenAccount** único (sua credencial principal)
* Um **limite de instâncias** que você pode criar
* Acesso a todas as instâncias dela

Pense nela como sua "área de cliente": dentro dela ficam suas instâncias, cada uma representando um número de WhatsApp conectado.

## Instância

Uma **instância** é uma conexão ativa com um número de WhatsApp. Cada instância tem:

* **Nome único na sua conta** (ex.: `minhaInstancia`, `suporte`, `atendimento`)
* **Token próprio** (TokenInstance) gerado automaticamente quando você cria a instância
* **Sessão persistente**, depois de conectar ao WhatsApp, ela se mantém ligada mesmo após reiniciar
* **Configurações individuais** (webhook, proxy, etc.)

<Info>
  O nome da instância aparece em toda URL com `:instance` no path. Exemplo: `POST /api/message/text/minhaInstancia` opera na instância chamada `minhaInstancia`.
</Info>

## Tokens: Account vs Instance

<CardGroup cols={2}>
  <Card title="TokenAccount" icon="users">
    Entregue quando sua conta foi criada. Usado para **administrar** sua conta.
    **Casos de uso**: criar, listar ou deletar instâncias.
  </Card>

  <Card title="TokenInstance" icon="key">
    Gerado pela API ao criar uma instância. Usado nas **operações do dia a dia**.
    **Casos de uso**: enviar mensagem, criar grupo, configurar webhook, etc.
  </Card>
</CardGroup>

Veja [Autenticação](/pt/guide/authentication) para detalhes sobre quando usar cada um.

## JID (Jabber ID)

Todo contato, grupo ou canal no WhatsApp tem um **JID**, um identificador único no estilo email. A API aceita e retorna JIDs em todos os endpoints que referenciam destinatários.

| Tipo               | Formato                   | Exemplo                        |
| ------------------ | ------------------------- | ------------------------------ |
| Usuário            | `<número>@s.whatsapp.net` | `5511999999999@s.whatsapp.net` |
| Grupo              | `<id>@g.us`               | `120363024567890123@g.us`      |
| Canal (newsletter) | `<id>@newsletter`         | `123456789@newsletter`         |

<Tip>
  Em endpoints de envio para contatos, **você pode passar só o número** (ex.: `5511999999999`) no campo `number`, a API monta o JID completo automaticamente. Para grupos, passe sempre o JID completo (o que termina em `@g.us`).
</Tip>

## Webhook vs WebSocket

A RyzeAPI oferece **dois canais complementares** para receber eventos em tempo real (novas mensagens, status de entrega, mudanças de grupo, etc.). Você pode usar os dois ao mesmo tempo.

<AccordionGroup>
  <Accordion title="Webhook (HTTP push)" icon="webhook">
    Quando um evento acontece na sua instância, a RyzeAPI faz uma requisição `POST` para a URL que você configurou.

    **Ideal para:** integrações servidor-a-servidor, CRMs, automações, bots.

    **Características:**

    * A RyzeAPI tenta novamente se seu endpoint estiver fora do ar (retry com backoff)
    * Você pode configurar até 3 webhooks simultâneos por instância (produção, staging, logging)
    * Pode incluir a mídia em base64 no corpo do webhook, ou apenas a URL
  </Accordion>

  <Accordion title="WebSocket (conexão persistente)" icon="plug">
    Seu cliente mantém uma conexão aberta com a RyzeAPI e recebe os eventos em tempo real pelo mesmo canal.

    **Ideal para:** dashboards ao vivo, aplicações browser, qualquer interface onde você quer ver as mensagens chegarem sem polling.

    **Características:**

    * Reconexão automática recomendada do lado do cliente
    * Mesmo shape de evento que o webhook
    * Autenticado via query string (`?token=`) quando em browser
  </Accordion>
</AccordionGroup>

### Os 6 tipos de evento

| Evento             | Quando acontece                               |
| ------------------ | --------------------------------------------- |
| `message.exchange` | Mensagem enviada ou recebida                  |
| `message.status`   | Mudança de status (enviada → entregue → lida) |
| `group.flow`       | Criação, saída ou alteração em grupo          |
| `instance.state`   | Conectou, desconectou, QR novo, logout        |
| `call.update`      | Chamada recebida, rejeitada, aceita           |
| `label.update`     | Etiqueta criada, renomeada, atribuída         |

## Formato das respostas

A API usa dois formatos de envelope, que podem variar entre os endpoints. Ambos começam com o campo `success` que indica se a operação deu certo.

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

    **Campos importantes:**

    * `success`: sempre presente
    * `message`: descrição humana do resultado
    * `status`: **código estável de negócio** (ex.: `sent`, `connected`, `qr_ready`). É o melhor campo para tratar respostas programaticamente
    * `data`: payload útil (varia por endpoint)
  </Tab>

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

    **Ordem de prioridade para tratamento:**

    1. O código HTTP (401, 403, 429, etc.), fonte de verdade
    2. O texto de `error.message`, quando precisar diferenciar dois erros do mesmo HTTP
  </Tab>
</Tabs>

Veja [Tipos de erro](/pt/guide/errors) para o catálogo completo de mensagens literais.

## Glossário rápido

| Termo             | Significado                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| **Conta**         | Sua área principal na RyzeAPI. Agrupa todas as suas instâncias, com uma cota de quantas você pode criar. |
| **Instância**     | Conexão ativa com um número de WhatsApp, gerenciada pela API.                                            |
| **TokenAccount**  | Seu token principal, usado para criar/listar/deletar instâncias.                                         |
| **TokenInstance** | Token da instância específica, usado nas operações do dia a dia.                                         |
| **JID**           | Identificador único no WhatsApp (contato, grupo ou canal) no formato email.                              |
| **Webhook**       | Requisição `POST` que a RyzeAPI faz para a sua URL quando um evento acontece.                            |
| **WebSocket**     | Conexão persistente que entrega eventos em tempo real para um cliente.                                   |
| **Pairing code**  | Código de 8 caracteres para conectar uma instância sem precisar escanear QR.                             |

## Variáveis usadas em exemplos

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

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