docs: add websocket event guide

Author: jrCleber

README.md

@@ -13,7 +13,7 @@ Portal oficial de documentação e referência técnica da CodeChat. Guias edito
 - Playground no navegador com cancelamento, timeout, resultado formatado e credenciais mascaradas.
 - Busca global por endpoint, rota, método, parâmetro, schema e evento (`Ctrl/Cmd + K`).
 - Catálogo de 41 webhooks reais: 27 por instância e 14 globais de Message Batch.
-- Guias editoriais existentes, changelog, migração e explicação explícita da ausência de WebSocket/SSE.
+- Guias editoriais existentes, changelog, migração e documentação do WebSocket de eventos.
 
 O relatório de consistência da referência fica em [`docs/api-reference-audit.md`](docs/api-reference-audit.md).
 

content/docs/changelog.mdx

@@ -3,6 +3,12 @@ title: "Changelog da documentação"
 description: "Marcos do portal e origem do conteúdo publicado."
 ---
 
+## 2026-07-14
+
+- Guia de WebSocket de eventos incorporado com URLs, autenticação, allowlist de eventos, payloads e códigos de fechamento.
+- Variáveis `WEBSOCKET_*` adicionadas à documentação de ambiente.
+- Message Batch passou a documentar `ownerUserId` como isolamento dos eventos globais em `/ws/global/events`.
+
 ## 2026-07-13
 
 - Referência própria criada com Next.js, React, Fumadocs e renderização dinâmica do OpenAPI.
@@ -11,6 +17,6 @@ description: "Marcos do portal e origem do conteúdo publicado."
 - Guia e referência das nove operações persistentes de Message Batch incorporados.
 - As nove operações e os eventos de Message Batch foram classificados como recurso Pro, sem enforcement no runtime.
 - Catálogo ampliado para 41 eventos de webhook: 27 por instância e 14 globais de lote.
-- Ausência de WebSocket/SSE e de enforcement Pro documentada explicitamente.
+- Limites de tempo real e enforcement Pro documentados explicitamente.
 
 O histórico do produto continua no repositório da API; esta página registra mudanças editoriais do portal.

content/docs/environment.mdx

@@ -29,6 +29,13 @@ description: "Variáveis de ambiente e configuração do servidor."
 | `WHATSAPP_SESSION_POSTGRES_URL` | Não | `postgres://...` | String de conexão opcional e dedicada do PostgreSQL para as sessões do whatsmeow. Quando vazia, `DATABASE_URL` é usada pelo SQL store do whatsmeow. |
 | `WEBHOOK_GLOBAL_URL` | Não | `https://example.com/webhook` | URL do webhook global. Precisa ser `http` ou `https` absoluta; obrigatória somente quando `WEBHOOK_GLOBAL_ENABLED=true`. |
 | `WEBHOOK_GLOBAL_ENABLED` | Não | `false` | Habilita o envio de todos os eventos reconhecidos de todas as instâncias para `WEBHOOK_GLOBAL_URL`. O padrão é `false`. |
+| `WEBSOCKET_ENABLED` | Não | `true` | Habilita as rotas `/ws/instance/events` e `/ws/global/events`. O padrão é `true`. |
+| `WEBSOCKET_ALLOWED_ORIGINS` | Não | `http://localhost:3000,http://localhost:5173` | Lista separada por vírgula de origens aceitas para browsers. Quando vazia, clientes com `Origin` são rejeitados. |
+| `WEBSOCKET_ALLOW_EMPTY_ORIGIN` | Não | `true` | Permite clientes backend sem header `Origin`. |
+| `WEBSOCKET_PING_INTERVAL` | Não | `25s` | Intervalo de ping do servidor WebSocket. |
+| `WEBSOCKET_PONG_TIMEOUT` | Não | `60s` | Prazo máximo para receber pong antes de encerrar a conexão. |
+| `WEBSOCKET_WRITE_TIMEOUT` | Não | `10s` | Prazo máximo de escrita de frames. |
+| `WEBSOCKET_SEND_BUFFER` | Não | `256` | Tamanho do buffer por cliente WebSocket. |
 | `AUTHENTICATION_JWT_EXPIRES_IN` | Sim | `3600` | Expiração do JWT em segundos. O valor `0` remove a claim `exp`. |
 | `AUTHENTICATION_JWT_SECRET` | Sim | `strong-secret` | Chave secreta usada para assinar JWTs com HS256. |
 | `AUTHENTICATION_GLOBAL_AUTH_TOKEN` | Sim | `admin-token` | Token usado somente para criar e listar instâncias. |

content/docs/events-overview.mdx

@@ -1,20 +1,22 @@
 ---
 title: "Visão geral de eventos"
-description: "Como a API transforma eventos internos em entregas HTTP por webhook."
+description: "Como a API transforma eventos internos em entregas por webhook e WebSocket."
 ---
 
-A implementação atual publica eventos somente por **webhooks HTTP POST**. Há dois fluxos: eventos por instância, com envelope contendo `instance`, e eventos globais de Message Batch, sem esse campo.
+A implementação atual publica eventos por **webhooks HTTP POST** e por **WebSocket**. Há dois escopos: eventos por instância, com envelope contendo `instance`, e eventos globais de Message Batch, sem esse campo.
 
 ## O que está implementado
 
 - 41 nomes públicos: 27 eventos por instância e 14 eventos globais de Message Batch.
 - Webhook por instância com flags em `events`.
 - Webhook global controlado por `WEBHOOK_GLOBAL_URL` e `WEBHOOK_GLOBAL_ENABLED`.
+- WebSocket por instância em `/ws/instance/events`.
+- WebSocket global em `/ws/global/events`.
 - Fila em memória com múltiplos workers para eventos por instância.
 - Outbox PostgreSQL com retry e backoff para eventos globais de Message Batch.
 
 ## Limites operacionais
 
 Eventos por instância não têm retry automático nem dead-letter queue. Eventos de Message Batch são reagendados pela outbox após falhas, com backoff persistente. Nenhum dos fluxos garante ordem ou assinatura HMAC; o `x-request-id` serve apenas para correlação.
 
-Também não há endpoint WebSocket ou Server-Sent Events no runtime auditado. Veja [Tempo real](/docs/realtime) para a decisão de integração correta.
+O WebSocket entrega em tempo real, mas em modo best-effort e sem replay automático. Veja [WebSocket de eventos](/docs/websocket) para URLs, autenticação, payloads e códigos de fechamento.

content/docs/faq.mdx

@@ -13,7 +13,7 @@ Sim, o middleware global aceita exatamente `apikey`, `x-api-key` e `apiKey`. Se
 
 ## A CodeChat oferece WebSocket?
 
-Não no runtime auditado. Não existem rota de upgrade, WebSocket ou SSE; tempo real é entregue por [webhooks](/api-reference/webhooks).
+Sim. A API expõe `/ws/instance/events` para eventos por instância e `/ws/global/events` para eventos globais de Message Batch. Consulte [WebSocket de eventos](/docs/websocket).
 
 ## Endpoints Pro retornam `402`?
 

content/docs/message-batches.mdx

@@ -16,6 +16,8 @@ apikey: <token-global>
 
 Os aliases `x-api-key` e `apiKey` também são aceitos pelas mesmas regras do middleware global. O token global é administrativo e, no runtime atual, não existe ACL adicional por usuário/instância. Na criação, todas as instâncias são consultadas, precisam existir e possuir autenticação; seus IDs internos e um snapshot dos nomes são persistidos. Nomes vazios ou repetidos são rejeitados.
 
+`ownerUserId` e opcional na criacao. Quando omitido, o valor persistido e `global`. Esse campo isola os eventos de WebSocket em `/ws/global/events`: o `sub` do JWT de usuario precisa ser igual ao `ownerUserId` do lote.
+
 ## Arquitetura e persistência
 
 - `message_batches`: definição, estado, lease e contadores derivados.
@@ -38,6 +40,7 @@ apikey: <token-global>
 ```json
 {
   "name": "Aviso de manutenção",
+  "ownerUserId": "user-123",
   "instances": ["codechat-01", "codechat-02"],
   "recipients": ["5531999999999", "5531888888888"],
   "message": {

content/docs/meta.json

@@ -23,6 +23,7 @@
     "---Eventos e entrega---",
     "events-overview",
     "webhooks",
+    "websocket",
     "envelope",
     "headers",
     "retries",

content/docs/migration.mdx

@@ -10,7 +10,7 @@ Use este roteiro ao substituir uma integração construída sobre as rotas legad
 - Mantenha separados o token global e o JWT da instância. A migração de rota não altera a finalidade de cada credencial.
 - Preserve os nomes, tipos e valores dos campos JSON até confirmar a operação equivalente no OpenAPI.
 - Não transforme aliases de headers, paths ou payloads em um contrato novo durante a troca de runtime.
-- Trate webhooks como o canal de eventos implementado. A API Go auditada não expõe WebSocket nem SSE.
+- Trate webhooks e WebSocket como canais distintos: webhooks para entrega HTTP e WebSocket para assinatura best-effort em tempo real.
 
 ## Rotas atuais e aliases
 

content/docs/realtime-events.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Eventos em tempo real"
-description: "Como consumir os eventos existentes sem inventar um transporte WebSocket ou SSE."
+description: "Como consumir os eventos por webhook ou WebSocket."
 ---
 
-Não há catálogo separado de eventos WebSocket/SSE. O catálogo implementado reúne **41 eventos de webhook**: 27 por instância e 14 globais de Message Batch, descritos em [Webhooks](/docs/webhooks#eventos).
+O catálogo implementado reúne **41 eventos públicos**: 27 por instância e 14 globais de Message Batch. Esses nomes são usados tanto nos [Webhooks](/docs/webhooks#eventos) quanto no [WebSocket de eventos](/docs/websocket).
 
-Uma arquitetura comum é:
+Uma arquitetura comum para entrega persistente é:
 
 1. CodeChat envia `POST` ao seu endpoint de webhook.
 2. Seu backend valida, persiste e reconhece a entrega com `2xx`.
 3. Seu backend publica o evento aos clientes autorizados pelo canal interno escolhido.
 
-O terceiro passo pertence à sua aplicação; nomes de salas, URLs, autenticação e semântica de reconexão não fazem parte do contrato atual da CodeChat API.
+Para consumo direto em tempo real, abra uma conexão WebSocket para `/ws/instance/events` ou `/ws/global/events`, informando exatamente um `event` e o `token` adequado na query string. O WebSocket é best-effort e não substitui persistência ou replay no seu backend.

content/docs/realtime.mdx

@@ -1,16 +1,17 @@
 ---
 title: "Tempo real"
-description: "O canal disponível hoje e o que não existe no runtime auditado."
+description: "Canais disponíveis para eventos HTTP e WebSocket."
 ---
 
 ## Estado atual
 
-A CodeChat API Go auditada **não registra endpoint WebSocket nem Server-Sent Events (SSE)**. Não existe URL de conexão, protocolo de inscrição ou cliente oficial para esses transportes no código atual.
+A CodeChat API Go entrega eventos por [webhooks HTTP](/docs/webhooks) e por [WebSocket de eventos](/docs/websocket). Webhooks são a integração persistente por HTTP POST; WebSocket é um canal em tempo real, best-effort, para assinar um evento por conexão.
 
-Eventos são entregues por [webhooks HTTP](/docs/webhooks). Para uma experiência em tempo real na sua aplicação, receba o webhook no seu backend e distribua o evento aos seus próprios clientes pelo transporte que você controla.
+Não há Server-Sent Events (SSE) documentado. Para integrações que exigem replay ou reconstrução de estado, combine WebSocket com os endpoints REST persistentes correspondentes.
 
-## Por que `/websocket` redireciona para cá
+## URLs principais
 
-URLs antigas ou esperadas como `/websocket` e `/websocket/events` são preservadas apenas como redirecionamentos informativos no portal. Elas não representam rotas da API e não devem ser usadas como endereço de conexão.
+- Eventos por instância: `ws://localhost:8084/ws/instance/events?event=connection.update&token=<INSTANCE_JWT>`
+- Eventos globais: `ws://localhost:8084/ws/global/events?event=message.batch.progress&token=<USER_JWT>`
 
-Se um transporte em tempo real for adicionado ao runtime no futuro, esta página e o OpenAPI devem ser atualizados a partir da implementação antes de publicar exemplos.
+Consulte [WebSocket de eventos](/docs/websocket) para autenticação, allowlist de eventos, payloads, heartbeat, códigos de fechamento e exemplo de cliente JavaScript.