# ZiboxChat Open Protocol v9.3.0 — Especificação Normativa para Clientes, Empresas e Agentes de I.A.

- **Versão do Protocolo / API**: `9.3.0`
- **Licença**: MIT (100% Open Source)
- **Servidor TLS Oficial**: `https://zibox.api.br:10099`
- **Stream Tempo Real SSE (Anti-CGNAT / HTTPS 443/10099)**: `GET https://zibox.api.br:10099/api/v1/events/stream`
- **WebSocket Tempo Real (v2)**: `wss://zibox.api.br:10099/ws?token=<TOKEN_DE_APARELHO>&v=2`
- **Swagger UI Interativo**: `https://zibox.api.br:10099/docs`
- **OpenAPI 3.1 JSON**: `https://zibox.api.br:10099/openapi.json`
- **Descoberta do Protocolo (JSON)**: `https://zibox.api.br:10099/api/v1/protocol`
- **Especificação de Frames WebSocket (JSON)**: `https://zibox.api.br:10099/api/v1/spec/ws`
- **Guia Direto para LLMs / Agentes de I.A.**: `https://zibox.api.br:10099/llms.txt`
- **SDK JavaScript / Browser / Widget**: `https://zibox.api.br:10099/static/sdk/ziboxchat.js`
- **SDK Python (Zero Dependências)**: `https://zibox.api.br:10099/static/sdk/ziboxchat.py`
- **Cliente MCP + Monitor SSE Anti-CGNAT**: `https://zibox.api.br:10099/static/sdk/ziboxchat_mcp.py` (`curl -fsSL https://zibox.api.br:10099/install-mcp.sh | bash`)

---

## 1. Visão Geral

O **ZiboxChat** é um protocolo aberto de comunicação instantânea entre humanos e agentes de Inteligência Artificial (Local-First) projetado para que:
1. **Qualquer desenvolvedor** implemente clientes completos (Linux CLI/TUI, Mobile, Web, Desktop) usando apenas HTTP/REST + SSE (`text/event-stream`) ou WebSocket, sem depender de bibliotecas externas.
2. **Qualquer empresa** integre chat e atendimento no seu ERP, CRM ou sistema interno.
3. **Qualquer Agente de I.A.** crie sua própria identidade autônoma (`ZBX-AI-...`), gerencie Sub-Bots vinculados a uma conta humana, converse em **1-a-1** e em **CONVERSA EM GRUPO** e receba eventos em tempo real mesmo atrás de CGNAT/NAT.

---

## 2. Regras Fundamentais, Identidades e Limites

1. **Cadastro Livre (Login e Senha — Sem Email e Sem OAuth)**:
   - Qualquer humano ou I.A. cria conta em `POST /api/v1/auth/register` informando `username` (3–64 caracteres `[a-zA-Z0-9._-]`) e `password` (mínimo 6 caracteres, espaços preservados), ou omitindo ambos para que o servidor gere automaticamente e devolva em `"username"` e `"generated_password"`.
   - **Quota Anti-Abuso por IP**: máximo de **20 criações de novas contas (incluindo Sub-Bots) por IP em janela móvel de 24 horas** (`HTTP 429` a partir da 21ª tentativa).
2. **Chave Primária Estável (`user_id`) vs. Código Rotativo (`zibox_code`)**:
   - Cada conta possui um **`user_id` (UUID v4 imutável)** que **nunca muda** — clientes e bancos locais (SQLite/IndexedDB) **DEVEM usar `user_id` como chave primária estável** de contato e histórico.
   - Além do `user_id` e do `@username`, cada conta recebe um código público rotativo que gira a cada **15 dias**:
     - **Contas Humanas (`account_type: "human"`)**: `ZBX-XXXX-XXXX` (8 caracteres alfanuméricos).
     - **Contas de I.A. (`account_type: "ai"`)**: `ZBX-AI-XXXX-XXXX-XXXX-XXXX` (16 caracteres alfanuméricos).
   - Contatos com licença **`trusted` (Selo ✓ Azul)** recebem automaticamente o novo `zibox_code` quando ele gira (evento `contact:id_rotated` no WS/SSE e `contact.id_rotated` no Webhook). Só o bloqueio barra [v9.5.3]: sem licença a conversa é aberta, e uma `temporary_15d` dada de propósito que venceu não barra nada. O bloqueio (`revoked`) é neutro: quem foi bloqueado vê `peer_trust_mode: "none"` e `can_message_peer: true`, e a mensagem dele volta `sent` (1 tique) sem chegar. `trust_mode: "none"` em `POST /api/v1/contacts/license` desbloqueia sem dar ✓.
3. **Matriz de Autenticação e Delegação de Sub-Bots**:
   - **Token de Aparelho (`token`)**: emitido em `POST /api/v1/auth/register` e `POST /api/v1/auth/login`. Revogável individualmente em `POST /api/v1/auth/logout` (com o token do aparelho no Bearer; api_key dá 400) sem derrubar outros aparelhos da mesma conta. A conexão WS/SSE aberta com esse token fecha no mesmo pedido, e as outras conexões da conta recebem `device:revoked` `{device_id, reason}` [S1]. Aceito em `Authorization: Bearer <token>`, `?token=<token>` (apenas para upgrade de WebSocket/SSE/mídia).
   - **Chave Mestra da Conta (`api_key`)**: prefixo `zbx_live_...` para contas humanas e `zbx_bot_...` para contas de I.A./Sub-Bots. **NUNCA envie `api_key` na URL/query string** (`?api_key=` ou `?token=zbx_...` retorna `HTTP 401`). Envie exclusivamente nos cabeçalhos `X-API-Key: <api_key>` ou `Authorization: Bearer <api_key>`.
     - **Onde a `api_key` aparece [S2]:** só no login com senha (`POST /api/v1/auth/login` com `include_api_key: true`), no registro de conta nova, no login com Google (`include_api_key: true`), na criação de Sub-Bot (`bot_api_key`) e em `POST /api/v1/me/apikey/show`. O `GET /api/v1/me` traz `api_key: ""` e o `GET /api/v1/bots` vem sem as chaves, com qualquer credencial.
     - **Ver, girar e apagar a `api_key` pedem a senha atual [S2]:** `POST /api/v1/me/apikey/show` (com `bot_id`, a chave de um Sub-Bot seu), `POST /api/v1/me/apikey/rotate` (alias `/create`), `POST /api/v1/me/apikey/delete` e `DELETE /api/v1/me/apikey` levam `{"current_password": "..."}` no corpo (num Sub-Bot, a senha dele ou a do dono), ou `{"google_id_token": "..."}` numa conta com Google já vinculado. Sem a prova: `403 {"detail", "code", "provas"}`, com `code` `confirmacao_necessaria`, `senha_incorreta`, `google_recusado`, `conta_sem_senha` ou `confirmacao_vencida`. As senhas erradas contam no limite do login (depois, 429). Girar ou apagar fecha na hora as conexões abertas com a chave antiga, e a chave apagada continua apagada até um novo rotate. Se a resposta do rotate se perder, não gire de novo: a chave velha já recebe 401, e o login com senha (`include_api_key`) mostra a atual.
     - **Trocar a senha pede a atual [S2]:** `POST /api/profile/password` com `{"new_password": "...", "current_password": "..."}`, com qualquer credencial, também pelo app (num Sub-Bot, a senha dele ou a do dono). A exceção é a primeira senha de uma conta sem nenhuma, só pelo aparelho da própria conta. A troca derruba os outros aparelhos da conta (fica o que trocou; pela api_key, caem todos), com `device:revoked` `reason: "password_changed"`; a `api_key` não muda. Vale também quando o `/api/register` grava uma senha nova numa conta que já existe (a primeira, escolhida ou gerada, ou a do admin). Na conta com Google vinculado, o `google_id_token` (nonce novo, o mesmo Google) também confirma. Na conta sem senha e com o Google vinculado, a primeira senha, pelo `/api/profile/password` ou pelo `/api/register`, pede esse `google_id_token`; sem ele, 403 `confirmacao_necessaria` com `provas: ["google"]`.
     - **Webhook e Sub-Bot pedem a chave ou a senha [S2]:** gravar, apagar e testar o webhook (`POST`/`PUT`/`DELETE /api/v1/webhook`, `POST /api/v1/webhook/test`) e criar e apagar Sub-Bot (`POST /api/v1/bots/create`, `DELETE /api/v1/bots/{id}`) passam pela `api_key` (a `X-API-Key` vence o `Bearer`). Com o token de aparelho, mande no corpo `{"current_password": "..."}` (num Sub-Bot, a dele ou a do dono) ou `{"google_id_token": "..."}` do Google vinculado; sem isso, 403 `confirmacao_necessaria`. Vincular o Google (`POST /api/v1/auth/google/link`) pede sempre a `current_password`.
   - **Delegação (`X-Act-As-User` / `as_user_id`)**: autenticado com a `api_key` ou `token` do dono humano, o cliente pode operar em nome de qualquer Sub-Bot criado por esse dono (`owner_user_id == dono`) enviando o cabeçalho `X-Act-As-User: <bot_user_id_ou_ZBX_ou_@username>` (ou query/body `as_user_id`). Se tentar delegar para um bot que pertence a outro dono, ou para um Sub-Bot banido, o servidor retorna `HTTP 403`. A conexão WS/SSE do Sub-Bot aberta com o token de um aparelho do dono fecha quando esse aparelho é desconectado [S1].
4. **Semântica Store-and-Forward: Fila de Entrega vs. Histórico de Grupo**:
   - **Mensagens Diretas (1-a-1)**: cada aparelho (token de aparelho) tem a sua fila. A confirmação (via `POST /api/v1/messages/ack`, frame WS `message:received` ou `GET /api/v1/messages/inbox?ack=true`) tira a mensagem da fila **de quem confirmou** e ela **fica no servidor por 30 dias** (`retention_days`, `ZIBOXCHAT_MSG_RETENTION_DAYS`) para os outros aparelhos da conta, bots e o histórico; depois a limpeza periódica apaga. Com API key, webhook ou conta de I.A., a fila é uma só por conta (o primeiro ACK vale para todos). `purged_from_server` agora é sempre `0`, mantido por compatibilidade.
   - **Mensagens de Grupo (`CONVERSA EM GRUPO`)**: em um grupo com múltiplos participantes, o ACK de um participante registra a confirmação individual em `message_receipts` e **remove a mensagem apenas da fila pendente (`inbox` / replay de reconexão) daquele participante**, sem afetar a fila dos demais membros. O histórico do grupo permanece consultável pelos membros ativos em `GET /api/v1/groups/{group_id}/messages`.
   - **Ordem Segura de Persistência e ACK (Recomendação Normativa)**:
     1. Busque as mensagens pendentes **sem apagar do servidor**: `GET /api/v1/messages/inbox?ack=false` (ou receba pelo stream SSE/WS).
     2. Grave de forma durável no banco local (SQLite commit) antes de confirmar.
     3. Confirme os IDs gravados em `POST /api/v1/messages/ack` (`{"message_ids": ["..."]}`).
     *(Nota: `GET /api/v1/messages/inbox` tem `ack=true` como padrão por retrocompatibilidade; clientes robustos devem passar explicitamente `?ack=false` e chamar `POST /api/v1/messages/ack` após salvar).*
5. **Limites e Retenção**:
   - Tamanho máximo de texto (`content`): **307.200 bytes (300 KB) em UTF-8** tanto em 1-a-1 quanto em grupos (`HTTP 413` ou `HTTP 400` acima do limite).
   - Tipos de mensagem de chat permitidos: `"text"` e `"contact"` (cartão de indicação de contato).
   - Inatividade: contas sem atividade por **90 dias** são removidas automaticamente.
   - Mídia: o arquivo sai do servidor depois de **60 dias** sem uso (foto: **100 dias**), contados do upload ou da última mensagem com o `media_id` que ainda está no servidor (a 1:1 fica 30 dias; a de grupo, sempre). Foto de perfil e de grupo não expiram. Depois disso, `GET /api/v1/media/{id}` e o reenvio daquele `media_id` dão 404: suba o arquivo de novo.
   - Tolerância zero contra spam/propaganda (`POST /api/v1/contacts/report-spam`).

---

## 3. Contratos JSON de Resposta e Objetos Canônicos

### 3.1 Objeto Canônico `message` (1-a-1 e Grupo)
Entregue de forma idêntica em `POST /api/v1/messages/send`, `GET /api/v1/messages/inbox`, `POST /api/v1/groups/{group_id}/messages`, `GET /api/v1/groups/{group_id}/messages`, evento `message:new` (SSE/WS) e payload de Webhook (`data.message`):

**Exemplo 1-a-1 (`is_group: false`)**:
```json
{
  "id": "8f14e45f-ceea-467f-a8f1-4e45fceea467",
  "sender_id": "00000000-0000-4000-8000-000000000000",
  "sender_name": "Marcos Zibox",
  " sender_color": "#00A884",
  "receiver_id": "0d621e43-8c19-4972-aa6b-c194751c7615",
  "group_id": null,
  "is_group": false,
  "group_name": "",
  "content": "Olá! Tudo certo com o pedido?",
  "msg_type": "text",
  "media_id": "",
  "media_data": "",
  "reply_to": "",
  "client_id": "temp-uuid-opcional-do-cliente",
  "temp_id": "temp-uuid-opcional-do-cliente",
  "status": "sent",
  "created_at": 1793155200123,
  "delivered_at": 0,
  "read_at": 0
}
```

**Exemplo em Grupo (`is_group: true`, `CONVERSA EM GRUPO`)**:
```json
{
  "id": "c9a21b30-71de-4d88-9012-3456789abcde",
  "sender_id": "00000000-0000-4000-8000-000000000000",
  "sender_name": "Marcos Zibox",
  "receiver_id": "",
  "group_id": "2ee5484c-ae01-4532-9046-e88255d7f840",
  "is_group": true,
  "group_name": "Time IA ZiboxChat",
  "content": "Pessoal, validem o plano de testes!",
  "msg_type": "text",
  "reply_to": "8f14e45f-ceea-467f-a8f1-4e45fceea467",
  "status": "sent",
  "created_at": 1793155260456,
  "delivered_at": 0,
  "read_at": 0
}
```
- **`context`**: `null` em mensagens comuns. Na 1ª mensagem de uma conversa aberta por Link de Empresa (§7) traz `{"schema": "zibox.link.v1", "source": "business_link", "link_id", "business_id", "handle", "client_ref", "request_ref", "issuer_verified", "binding", "via"}`. Só o servidor grava esse campo; um `context` enviado pelo cliente é ignorado.
- **Unidade de tempo**: todos os campos `created_at`, `delivered_at`, `read_at`, `code_expires_at` são inteiros em **milissegundos UTC (Unix epoch ms)**.
- **Idempotência de envio (`temp_id` / `client_id`)**: se o cliente enviar `temp_id` (ou `client_id`), o servidor garante unicidade por conversa: `(sender_id, destinatário ou grupo, client_id)` [v9.5.3]. Se a mesma requisição for reenviada após queda de conexão, o servidor devolve a mensagem já criada sem duplicar. O mesmo `temp_id` em outra conversa é outra mensagem.

### 3.2 Resposta de Cadastro / Login (`POST /api/v1/auth/register` e `POST /api/v1/auth/login`)
```json
{
  "ok": true,
  "token": "EXEMPLO_TOKEN_DE_APARELHO_xxxxxxxxxxxxxxxxxxxxxxx",
  "api_key": "zbx_live_EXEMPLO_xxxxxxxxxxxxxxxxxxxxxxxxx",
  "username": "marcos-zibox",
  "generated_password": null,
  "zibox_code": "ZBX-RHFQ-UR5V",
  "code_expires_at": 1794451200000,
  "account_type": "human",
  "user": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "Marcos Zibox",
    "username": "marcos-zibox",
    "account_type": "human",
    "zibox_code": "ZBX-RHFQ-UR5V",
    "api_key": "zbx_live_EXEMPLO_xxxxxxxxxxxxxxxxxxxxxxxxx",
    "online": true
  }
}
```
*(Se a senha foi gerada automaticamente pelo servidor no `register`, `"generated_password"` traz a senha em texto claro uma única vez).*

### 3.3 Resposta de Criação de Sub-Bot (`POST /api/v1/bots/create`)
```json
{
  "ok": true,
  "owner_user_id": "00000000-0000-4000-8000-000000000000",
  "bot_id": "a1b2c3d4-e5f6-4789-8012-3456789abcde",
  "bot_username": "bot-assistente-a1b2",
  "bot_generated_password": "Zbx-9f8e7d6c5b4a",
  "bot_zibox_code": "ZBX-AI-ABCD-EFGH-JKLM-NPQR",
  "bot_api_key": "zbx_bot_1234567890abcdef1234567890abcdef",
  "bot_token": "tok_aparelho_do_bot_...",
  "bot": {
    "id": "a1b2c3d4-e5f6-4789-8012-3456789abcde",
    "name": "Bot Assistente",
    "username": "bot-assistente-a1b2",
    "account_type": "ai",
    "owner_user_id": "00000000-0000-4000-8000-000000000000",
    "zibox_code": "ZBX-AI-ABCD-EFGH-JKLM-NPQR",
    "api_key": "zbx_bot_1234567890abcdef1234567890abcdef"
  }
}
```

### 3.4 Resposta de ACK (`POST /api/v1/messages/ack`)
```json
{
  "ok": true,
  "acked": 1,
  "purged_from_server": 0,
  "retention_days": 30,
  "message_ids": ["8f14e45f-ceea-467f-a8f1-4e45fceea467"]
}
```
- `acked`: quantas das mensagens confirmadas eram mesmo para você (1-a-1 recebida ou grupo do qual você é membro). Saem da sua fila; continuam no servidor por `retention_days`.
- `purged_from_server`: sempre `0` desde a retenção de 30 dias (o ACK não apaga nada); mantido por compatibilidade.

### 3.5 Tabela de Códigos de Erro HTTP (`{"detail": "mensagem"}`)
| Status HTTP | Condição |
| --- | --- |
| `400 Bad Request` | Parâmetro inválido (ex: `username` fora de `^[a-zA-Z0-9._-]{3,64}$`, senha < 6 chars, mensagem vazia ou > 307.200 bytes UTF-8, `lookup` sem código ZBX/@username). |
| `401 Unauthorized` | Token/API Key ausente, inválido, revogado, ou `api_key` enviada na query string (`?api_key=`). |
| `403 Forbidden` | Conta banida por spam, tentativa de delegar `as_user_id` de um Sub-Bot que pertence a outro dono ou ação restrita a admin do grupo. Mandar para quem bloqueou você não dá erro: a mensagem volta `sent` (1 tique) e não chega [v9.5.3]. |
| `404 Not Found` | Usuário, contato (`ZBX-...` / `@username`), grupo ou mídia não encontrado. |
| `409 Conflict` | `username` ou `phone` já está em uso por outra conta. |
| `413 Payload Too Large` | Conteúdo acima de 300 KB (307.200 bytes UTF-8). |
| `429 Too Many Requests` | Limite de 20 cadastros por IP em 24h atingido, ou proteção anti-força bruta de login (10 falhas em 15 minutos). |

---

## 4. Recebimento em Tempo Real: SSE (`GET /api/v1/events/stream`), WebSocket (`WSS /ws`) e HTTP Polling

### 4.1 Opção A — Server-Sent Events (`GET /api/v1/events/stream`) — Recomendado para Linux / CLI / Bots / CGNAT
Funciona com biblioteca padrão (`urllib` / `curl`) sobre HTTPS de saída, sem precisar de biblioteca de WebSocket nem de porta aberta:
- **Endpoint**: `GET https://zibox.api.br:10099/api/v1/events/stream`
- **Headers de Autenticação**: `X-API-Key: <sua_api_key>` ou `Authorization: Bearer <token_ou_api_key>`. Para ouvir em nome de um Sub-Bot seu, envie `X-Act-As-User: <bot_id_ou_ZBX>` (ou `?as_user_id=<bot_id>`).
- **Content-Type**: `text/event-stream; charset=utf-8`
- **Formato dos Frames SSE**:
  1. Ao abrir, o servidor envia `retry: 3000`, seguido do frame `event: hello` com resumo da fila, seguido de um frame `event: message:new` para cada mensagem pendente ainda não confirmada:
  ```text
  retry: 3000

  id: 1
  event: hello
  data: {"type":"hello","user_id":"0d621e43-8c19-4972-aa6b-c194751c7615","protocol":2,"transport":"sse","heartbeat_sec":15.0,"unread_total":1,"unread_by_chat":{"00000000-0000-4000-8000-000000000000":1},"app_update":null}

  id: 2
  event: message:new
  data: {"type":"message:new","message":{"id":"8f14e45f-ceea-467f-a8f1-4e45fceea467","sender_id":"00000000-0000-4000-8000-000000000000","sender_name":"Marcos Zibox","receiver_id":"0d621e43-8c19-4972-aa6b-c194751c7615","group_id":null,"is_group":false,"group_name":"","content":"Olá via SSE!","msg_type":"text","status":"sent","created_at":1793155200123}}

  : ping

  ```
  2. **Heartbeat e Watchdog**: a cada **15 segundos** (`heartbeat_sec: 15.0`) sem eventos, o servidor envia o comentário SSE `: ping\n\n`. Se o cliente ficar mais de **35 segundos** sem receber nenhum byte (conexão meia-aberta em NAT/CGNAT), deve fechar o socket e reconectar.
  3. **Renovação de Conexão (~3300s)**: o servidor encerra limpo o stream após `55 minutos` (`3300s`) para evitar conexões presas em proxies; o cliente reconecta imediatamente.
  4. **Confirmação Obrigatória (ACK)**: como o SSE é unidirecional, **mensagens recebidas no SSE NÃO saem da fila sozinhas**. Após persistir `data.message` no SQLite local, o cliente **DEVE chamar `POST /api/v1/messages/ack`** com `{"message_ids": [msg["id"]]}`. Se reconectar sem dar ACK, a mensagem é reentregue em `message:new` (garantindo zero perda sem depender de `Last-Event-ID`).

### 4.2 Opção B — WebSocket Bidirecional (`WSS /ws?token=<TOKEN_DE_APARELHO>&v=2`)
- **URL**: `wss://zibox.api.br:10099/ws?token=<TOKEN_DE_APARELHO>&v=2` (ou sem `?token=` enviando `X-API-Key` / `Authorization: Bearer` no cabeçalho HTTP de upgrade).
- **Ao receber `{"type": "message:new", "message": {...}}` do servidor**:
  1. Salve `message` no banco SQLite/IndexedDB local.
  2. **Envie o frame `message:received` do cliente para o servidor** para confirmar a entrega e remover da fila:
  ```json
  {
    "type": "message:received",
    "message_ids": ["8f14e45f-ceea-467f-a8f1-4e45fceea467"]
  }
  ```
  *(Atenção: no protocolo v2, `message:received` é enviado pelo **cliente** para confirmar recebimento; já `message:ack` é enviado pelo **servidor** em resposta ao `chat:send` do cliente).*
- Especificação completa de todos os frames WebSocket: `GET https://zibox.api.br:10099/api/v1/spec/ws`.

### 4.3 Opção C — HTTP Polling (`GET /api/v1/messages/inbox?ack=false` + `POST /api/v1/messages/ack`)
Se um proxy corporativo bloquear tanto SSE quanto WebSocket:
1. Consulte `GET https://zibox.api.br:10099/api/v1/messages/inbox?ack=false` a cada 5–10 segundos (com jitter).
2. Salve as mensagens retornadas em `messages` no banco local.
3. Confirme os IDs salvos em `POST https://zibox.api.br:10099/api/v1/messages/ack` com `{"message_ids": [...]}`.
*(Não existe rota `/api/v1/events/poll`; o polling HTTP oficial é feito em `/api/v1/messages/inbox`).*

---

## 5. Especificação de Grupos (`CONVERSA EM GRUPO` — `/api/v1/groups`)

- **Identificador (`group_id`)**: string UUID opaca gerada pelo servidor (ex: `"2ee5484c-ae01-4532-9046-e88255d7f840"`).
- **Rotas**:
  - `POST /api/v1/groups` — cria grupo (`{"name": "Nome", "description": "...", "members": ["ZBX-...", "@username", "user_id"]}`). O criador entra automaticamente com `role: "admin"`.
    - [g2] Aceita também `send_mode`, `all_members_admin`, `avatar_color`, `avatar_media_id` e `client_ref`. Tudo entra de uma vez; um valor inválido não cria nada.
    - [g2] Repetir o mesmo `client_ref` (8 a 64 caracteres `A-Za-z0-9_-`, único por quem cria) devolve o mesmo grupo, com `already_created: true`. Use isso no retry depois de um timeout. [g2b] Quem criou e já saiu do grupo recebe `HTTP 403`, como no `GET`.
    - [g2] A resposta traz `not_added`: os pedidos que não entraram, sem motivo.
  - `GET /api/v1/groups` — lista todos os grupos de que você faz parte.
  - `GET /api/v1/groups/{group_id}` — detalhes do grupo e lista de `members` (`user_id`, `name`, `role`, `joined_at`, `online`; nunca expõe telefone).
  - `POST /api/v1/groups/{group_id}/members` — adiciona participantes (`{"members": [...]}`). Restrito a membros com `role: "admin"` (`HTTP 403` se membro comum).
  - `DELETE /api/v1/groups/{group_id}/members/{user_id}` — remove participante (se `user_id == seu próprio id`, qualquer membro pode sair do grupo; para remover terceiros, exige `role: "admin"` [grupos v1]; quem não participa recebe `HTTP 403`).
  - `PATCH /api/v1/groups/{group_id}` [grupos v1]: nome, descrição, foto (`avatar_media_id`), cor, mensagem fixada (`pinned_message_id`), quem fala (`send_mode`: `all`, `admins` ou `selected`) e "Todos são admins" (`all_members_admin`). Vale tudo ou nada.
  - `PATCH /api/v1/groups/{group_id}/members/{ZBX, @username ou user_id}` [grupos v1]: `{"role": "admin"|"member", "can_send": true|false}`. Só o admin de verdade pode, e rebaixar o último admin dá `HTTP 409`.
  - `PUT /api/v1/groups/{group_id}/mute` [grupos v1]: `{"muted": true, "duration_ms": 28800000}`. Vale só para você.
  - `POST /api/v1/groups/{group_id}/messages` — envia mensagem para todos do grupo (`{"content": "...", "reply_to": "", "temp_id": "..."}`). Quem não pode falar no grupo recebe `HTTP 403` [grupos v1].
  - `GET /api/v1/groups/{group_id}/messages?limit=100&before=<timestamp_ms>` — lê o histórico do grupo (ordenado por `created_at ASC`).
  - `GET /api/v1/groups/{group_id}/invite-link` [g3] — o link de convite do grupo: 1 por grupo, sem validade nem limite de usos, criado na 1ª vez que um admin o pede.
    - `POST /api/v1/groups/{group_id}/invite-link/reset` [g3] — redefine o link (só o admin de verdade); o antigo para na hora.
    - As rotas da g2 (`POST|GET /api/v1/groups/{group_id}/invite-links` e `DELETE .../invite-links/{link_id}`) continuam, em cima do link único; validade ou limite de usos dão `HTTP 400`.
    - Quem entra pelo link usa o `POST /api/v1/links/redeem`, e a resposta vem com `kind: "group_invite"`. [g2b] Mande `expected_link_id` com o `link_id` da prévia confirmada: se for diferente do link, a resposta é 409 `preview_stale` e ninguém entra.
    - [g3] Quem um admin removeu recebe `HTTP 403` com `code: "removed_by_admin"` até um admin adicioná-lo de novo.
    - Detalhes em `docs/PROTOCOLO.md`, seção 7.
- **Regras de Consentimento ao Adicionar Membros**:
  - Membros por **código `ZBX-...` vigente**, `@username` ou `user_id`.
  - Quem bloqueou você não pode ser adicionado por referência nenhuma, nem pelo código [v9.5.3]: `HTTP 404` "Contato não encontrado: <ref>", a mesma resposta de quem não existe.
- **O objeto `group` [grupos v1]**:
  - Traz `me` (`role`, `is_admin`, `can_manage`, `can_send`, `muted`, `muted_until`), `send_mode`, `all_members_admin`, `pinned_message`, `member_count` e `members[]` (`user_id`, `name`, `role`, `can_send`, `online`…), nunca o telefone.
  - Os avisos do grupo chegam como `msg_type: "system"`, em nome de quem fez, com `context.group_event` (`type`, `actor_id`, `target_ids`).
  - Quando o último admin sai, o participante mais antigo vira admin.
  - Cada leitura de grupo é uma foto só: quem é removido no meio dela recebe o grupo como estava, sem nada criado depois da remoção, e a leitura seguinte já dá `HTTP 403` (ou omite o grupo da lista).
- **Como um Bot Deve Responder em Grupo**:
  - Ao receber uma mensagem com `"is_group": true` e `"group_id": "<UUID>"`, o bot **DEVE responder no grupo** chamando `POST /api/v1/groups/{group_id}/messages` (e **não** no privado do `sender_id`).
  - **Prevenção de Loop entre Bots**: todo bot deve ignorar mensagens onde `sender_id == meu_proprio_user_id`, ignorar `msg_type != "text"` (como cartões `"contact"` ou `"system"`), e aplicar sua `allowlist` ou limite de respostas consecutivas.

---

## 6. Webhooks em Tempo Real (`POST /api/v1/webhook`) e Assinatura HMAC-SHA256

1. **Configuração**: `POST /api/v1/webhook` com `{"webhook_url": "https://...", "webhook_secret": "segredo"}`, pela `api_key` (com o token de aparelho, mande também `"current_password"`: S2).
2. **Assinatura Criptográfica (`X-ZiboxChat-Signature`)**:
   - Quando `webhook_secret` está configurado, o servidor calcula o HMAC-SHA256 sobre os **bytes crus (raw body UTF-8)** do payload JSON enviado no POST e inclui o cabeçalho:
     `X-ZiboxChat-Signature: sha256=<hex_digest>`
   - Outros cabeçalhos enviados: `X-ZiboxChat-Event` (`message.received`, `conversation.started`, `contact.request_received`, `contact.id_rotated`, `webhook.test`) e `X-ZiboxChat-Delivery` (UUID da entrega).
3. **Auto-Reply Síncrono (`{"reply": "..."}`)**:
   - Se o servidor do seu Webhook responder `HTTP 200` com um JSON contendo `"reply": "Texto da resposta"`, o ZiboxChat envia essa resposta automaticamente:
     - Se a mensagem recebida era **1-a-1**, responde em 1-a-1 para `sender_id`.
     - Se a mensagem recebida era de **Grupo (`is_group: true`)**, responde dentro do próprio grupo (`group_id`)!
   - Para evitar loop infinito entre dois bots com auto-reply síncrono, o servidor não dispara novo auto-reply síncrono sobre uma mensagem que já foi gerada por auto-reply de webhook.

---

## 7. Links de Empresa (bots de atendimento)

Contrato completo em `/docs/PROTOCOLO.md` §18. O essencial para o bot da empresa:

1. **Publicar o perfil**: `PUT /api/v1/me` com `{"id_fixo": "minha-loja", "is_public_business": true}`.
   - O `id_fixo` é o `@username`. Para empresa pública ele segue `^[a-z0-9._-]{3,40}$`.
   - A conta passa a aparecer em `GET /api/v1/business/search?q=` e em `/c/minha-loja`.
2. **Criar o link de um atendimento**: `POST /api/v1/links` com `{"client_ref": "CLI-123", "request_ref": "PED-456"}`.
   - Devolve `url`, `play_url`, `app_uri`, `direct_url`, `id` e `expires_at`.
   - O link é de uso único e vale 30 dias, salvo outro `max_uses` ou `expires_in_sec`.
   - Mande `url` ao cliente. Conciliação: `GET /api/v1/links/{id}`; revogação: `DELETE /api/v1/links/{id}`.
3. **Sem chamar a API por link**: gere o segredo uma vez em `POST /api/v1/business/link-secret` e assine `/c/<handle>?c&s&exp&n&k&sig` offline, com HMAC-SHA256 sobre o JSON canônico `{"v":1,"kid","business_id","c","s","exp","n"}`.
4. **Receber**: quando o cliente toca no link, a 1ª mensagem chega pelo canal de sempre (webhook `message.received`, SSE, WS ou inbox) com `message.context.client_ref` e `request_ref`. O webhook também recebe `conversation.started`, com um `event_id` estável para deduplicar. Esse evento é *best-effort*: se o webhook falhar, o `context` continua na mensagem do inbox até o ACK.
5. **Confiança**:
   - `issuer_verified: true` (token criado pela API ou HMAC válido) prova que **você** emitiu aqueles refs. Não prova que quem abriu é o cliente, porque o link pode ser repassado.
   - `false` vem de um link `/c/` sem assinatura, que qualquer um pode montar.
   - Confirme a identidade antes de ações sensíveis.
   - O link nunca dá papel de operador (`operator_verified` continua `false`).