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.
parent
293dbcf35b
commit
e839804436
148
Whatsapp.md
148
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user