From e839804436649e62cb16b90b3209d5fb5fb399fe Mon Sep 17 00:00:00 2001 From: Rafael Lopes Date: Wed, 22 Jul 2026 17:20:30 -0300 Subject: [PATCH] DOC: Atualiza modulo WhatsApp para refletir Meta Cloud API Remove referencias a whatsapp-web.js/Puppeteer. Adiciona MediaStorageService, rotas de send-media, tabela de tipos/limites de midia e proximos passos atualizados. --- Whatsapp.md | 148 +++++++++++++++++++++++++++------------------------- 1 file changed, 76 insertions(+), 72 deletions(-) diff --git a/Whatsapp.md b/Whatsapp.md index d9d1beb..824a86c 100644 --- a/Whatsapp.md +++ b/Whatsapp.md @@ -1,103 +1,107 @@ -# Modulo WhatsApp - -Base tecnica: - +# Modulo WhatsApp + +Base tecnica: + - Controller: `src/modules/whatsapp/whatsapp.controller.ts` - Service: `src/modules/whatsapp/whatsapp.service.ts` +- Config Service: `src/modules/whatsapp/whatsapp-config.service.ts` - Template Service: `src/modules/whatsapp/whatsapp-template.service.ts` - Template Repository: `src/modules/whatsapp/repositories/whatsapp-template.repository.ts` +- Media Storage: `src/modules/whatsapp/media/media-storage.service.ts` +- Media Adapter (disco local): `src/modules/whatsapp/media/adapters/local-disk.adapter.ts` - Contacts Service: `src/modules/contacts/contacts.service.ts` - Attendance Assignment: `src/modules/attendance/attendance-assignment.service.ts` - Attendance Repository: `src/modules/attendance/repositories/attendance-assignment.repository.ts` - Agent Presence: `src/modules/agent/agent-presence.service.ts` - Gateway: `src/modules/whatsapp/whatsapp.gateway.ts` - Prefixo: `/whatsapp` - -## Responsabilidade - -Integra com `whatsapp-web.js`, controla sessao, QR Code, chats, mensagens, midia e templates do canal WhatsApp. + +## Responsabilidade + +Integra com a **API oficial da Meta (Cloud API)**. Controla recebimento e envio de mensagens e midias, templates HSM e configuracao do canal. Fila, atribuicao, transferencia, fechamento e triagem do atendimento ficam no modulo `attendance`, mas algumas rotas continuam expostas em `/whatsapp` por compatibilidade com o frontend. - -## Endpoints - -| Metodo | Rota | Descricao | -|---|---|---| -| GET | `/whatsapp/status` | Status da sessao WhatsApp | -| GET | `/whatsapp/chats` | Lista conversas | -| GET | `/whatsapp/messages/:chatId` | Lista mensagens de uma conversa | -| GET | `/whatsapp/media/:chatId/:messageId` | Baixa midia de mensagem | -| POST | `/whatsapp/send` | Envia texto/midia | -| POST | `/whatsapp/start-attendance` | Inicia atendimento ativo por template | -| POST | `/whatsapp/assign` | Assume conversa | -| POST | `/whatsapp/transfer` | Transfere conversa | -| DELETE | `/whatsapp/release/:chatId` | Libera conversa | -| POST | `/whatsapp/close` | Fecha atendimento | -| GET | `/whatsapp/assignment/:chatId` | Consulta atribuicao | -| GET | `/whatsapp/templates` | Lista templates | -| POST | `/whatsapp/templates` | Cria template | -| POST | `/whatsapp/templates/update/:id` | Atualiza template | -| POST | `/whatsapp/templates/approve-admin/:id` | Aprova template pelo admin | -| POST | `/whatsapp/templates/reject-admin/:id` | Reprova template pelo admin | -| DELETE | `/whatsapp/templates/:id` | Remove template | - -## Funcoes importantes - + +## Endpoints + +| Metodo | Rota | Descricao | +|---|---|---| +| GET | `/whatsapp/status` | Status da conexao WhatsApp | +| GET | `/whatsapp/chats` | Lista conversas | +| GET | `/whatsapp/messages/:chatId` | Lista mensagens de uma conversa | +| GET | `/whatsapp/media/:chatId/:messageId` | Retorna midia de mensagem recebida | +| POST | `/whatsapp/send` | Envia texto | +| POST | `/whatsapp/send-media` | Envia midia (multipart/form-data com Multer) | +| GET | `/whatsapp/webhook` | Verificacao do webhook Meta | +| POST | `/whatsapp/webhook` | Recebe eventos do webhook Meta | +| POST | `/whatsapp/start-attendance` | Inicia atendimento ativo por template | +| POST | `/whatsapp/assign` | Assume conversa | +| POST | `/whatsapp/transfer` | Transfere conversa | +| DELETE | `/whatsapp/release/:chatId` | Libera conversa | +| POST | `/whatsapp/close` | Fecha atendimento | +| GET | `/whatsapp/assignment/:chatId` | Consulta atribuicao | +| GET | `/whatsapp/templates` | Lista templates | +| POST | `/whatsapp/templates` | Cria template | +| POST | `/whatsapp/templates/sync-meta` | Sincroniza status dos templates com a Meta | +| POST | `/whatsapp/templates/update/:id` | Atualiza template | +| POST | `/whatsapp/templates/:id/submit-meta` | Envia template para aprovacao da Meta | +| DELETE | `/whatsapp/templates/:id` | Remove template | + +## Funcoes importantes + ### `whatsapp.service.ts` -- Inicializa cliente WhatsApp Web. -- Emite QR/status. -- Lista chats e mensagens. -- Envia mensagens e midias. -- Dispara roteamento do bot ao receber mensagem. -- Executa abertura ativa com template. -- Nao cria schema de templates em runtime; `whatsapp_templates` deve existir via migrations. -- Usa `ContactsService` para enriquecer chats com nome, telefone, email, etiqueta e observacao. +- `handleMetaWebhookEvent()` — entry point do webhook, delega para `handleMetaIncomingMessage()` +- `handleMetaIncomingMessage()` — processa mensagem recebida, baixa midia se necessario via `downloadMetaMedia()` +- `downloadMetaMedia()` — busca URL temporaria da Meta e baixa o binario +- `sendMessage()` — envia texto via Meta API +- `sendMediaMessage()` — faz upload da midia para `/{phone_number_id}/media`, recebe `media_id` e envia a mensagem; salva no banco e emite via Socket.IO + +### `whatsapp-config.service.ts` + +- Gerencia configuracao do canal na tabela `whatsapp_config` (access_token, phone_number_id, api_version, webhook_token). +- Configuracao nao fica em variavel de ambiente; e gerenciada pelo painel admin. + +### `media-storage.service.ts` + +- Abstrai persistencia de arquivos de midia. +- Adapter atual: `LocalDiskAdapter` — salva em `./uploads/media/` com nome UUID. +- URL publica montada com `BASE_URL` do ambiente. +- `AppModule` serve o diretorio via `ServeStaticModule` em `/uploads`. +- Adapter futuro (SharePoint/S3) so precisa implementar a mesma interface. ### `whatsapp-template.service.ts` -- Lista, cria, edita, aprova, reprova e remove templates. -- Simula aprovacao Meta por tempo para o fluxo de demo. -- Mantem regra de negocio de template fora do adaptador WhatsApp. - -### `whatsapp-template.repository.ts` - -- Concentra SQL da tabela `whatsapp_templates`. -- Usa migrations como fonte do schema. +- Lista, cria, edita e remove templates. +- Sincroniza status com a Meta via `sync-meta`. +- Mantem regra de negocio de template fora do adaptador de canal. ### `attendance-assignment.service.ts` - Controla fila e atribuicao em `whatsapp_chat_atribuicoes`. - Impede envio quando atendimento ativo aguarda resposta do cliente. - Roteia conversas por area, fluxo configurado ou arvore do bot. -- Monta observacao de transferencia do Agente Virtual. - Consulta `AgentPresenceService` antes de atribuir atendimento a um usuario. -- Nao cria/altera schema em runtime; `whatsapp_chat_atribuicoes` deve ser mantida pelas migrations. -### `attendance-assignment.repository.ts` +## Midia — tipos e limites aceitos em `send-media` -- Concentra SQL de atribuicao, fila, transferencia, triagem e leitura do fluxo do bot. -- Mantem o service focado em regra de negocio e orquestracao. - -## Eventos em tempo real - -O `whatsapp.gateway.ts` usa Socket.IO para notificar o frontend sobre: - -- novas mensagens; -- atualizacoes de chat; -- status/QR quando aplicavel. - -## Code review +| Tipo | Formatos | Limite | +|---|---|---| +| Imagem | jpeg, png, webp, gif | 5 MB | +| Audio | mpeg, mp4, ogg, wav, aac, amr | 16 MB | +| Video | mp4, 3gpp | 16 MB | +| Documento | pdf, docx, xlsx | 100 MB | -- `attendance-assignment.service.ts` concentra regra critica e deve receber testes. -- `whatsapp.controller.ts` usa DTOs para validar payloads de envio, atendimento, transferencia e templates. -- Permissao de agente/admin ainda precisa ser validada no backend. -- `whatsapp-web.js` e bom para demo/MVP controlado, mas para producao robusta avaliar WhatsApp Cloud API. +## Eventos em tempo real + +O `whatsapp.gateway.ts` usa Socket.IO para notificar o frontend sobre: + +- novas mensagens (texto e midia); +- atualizacoes de chat; +- status de conexao. ## Proximos passos -- Persistir conversas e mensagens no PostgreSQL para auditoria. -- Guardar anexos fora do banco, com metadados em `message_attachments` e arquivo em VM Linux, AWS S3, Azure Blob ou SharePoint. +- Adicionar IA no primeiro atendimento, com configuracao no painel admin para escolher o provedor/modelo. +- Migrar storage de midia para SharePoint ou S3 (so trocar o adapter no `MediaStorageService`). - Evoluir `chat` para modulo omnichannel, recebendo eventos normalizados de WhatsApp, Email, SMS e Instagram. -- Substituir `whatsapp-web.js` pela API oficial da Meta. -- Adicionar IA no primeiro atendimento, com configuracao no painel admin para escolher o provedor/modelo de IA.