Sothis/omnichannel-backend
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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.
Rafael Alves Lopes 2026-07-22 17:20:30 -03:00
parent 293dbcf35b
commit e839804436
1 changed files with 76 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
Whatsapp.md

@ -4,8 +4,11 @@ Base tecnica:
- Controller: `src/modules/whatsapp/whatsapp.controller.ts` - Controller: `src/modules/whatsapp/whatsapp.controller.ts`
- Service: `src/modules/whatsapp/whatsapp.service.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 Service: `src/modules/whatsapp/whatsapp-template.service.ts`
- Template Repository: `src/modules/whatsapp/repositories/whatsapp-template.repository.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` - Contacts Service: `src/modules/contacts/contacts.service.ts`
- Attendance Assignment: `src/modules/attendance/attendance-assignment.service.ts` - Attendance Assignment: `src/modules/attendance/attendance-assignment.service.ts`
- Attendance Repository: `src/modules/attendance/repositories/attendance-assignment.repository.ts` - Attendance Repository: `src/modules/attendance/repositories/attendance-assignment.repository.ts`
@ -15,7 +18,7 @@ Base tecnica:
## Responsabilidade ## Responsabilidade
Integra com `whatsapp-web.js`, controla sessao, QR Code, chats, mensagens, midia e templates do canal WhatsApp. 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. Fila, atribuicao, transferencia, fechamento e triagem do atendimento ficam no modulo `attendance`, mas algumas rotas continuam expostas em `/whatsapp` por compatibilidade com o frontend.
@ -23,11 +26,14 @@ Fila, atribuicao, transferencia, fechamento e triagem do atendimento ficam no mo
| Metodo | Rota | Descricao | | Metodo | Rota | Descricao |
|---|---|---| |---|---|---|
| GET | `/whatsapp/status` | Status da sessao WhatsApp | | GET | `/whatsapp/status` | Status da conexao WhatsApp |
| GET | `/whatsapp/chats` | Lista conversas | | GET | `/whatsapp/chats` | Lista conversas |
| GET | `/whatsapp/messages/:chatId` | Lista mensagens de uma conversa | | GET | `/whatsapp/messages/:chatId` | Lista mensagens de uma conversa |
| GET | `/whatsapp/media/:chatId/:messageId` | Baixa midia de mensagem | | GET | `/whatsapp/media/:chatId/:messageId` | Retorna midia de mensagem recebida |
| POST | `/whatsapp/send` | Envia texto/midia | | 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/start-attendance` | Inicia atendimento ativo por template |
| POST | `/whatsapp/assign` | Assume conversa | | POST | `/whatsapp/assign` | Assume conversa |
| POST | `/whatsapp/transfer` | Transfere conversa | | POST | `/whatsapp/transfer` | Transfere conversa |
@ -36,68 +42,66 @@ Fila, atribuicao, transferencia, fechamento e triagem do atendimento ficam no mo
| GET | `/whatsapp/assignment/:chatId` | Consulta atribuicao | | GET | `/whatsapp/assignment/:chatId` | Consulta atribuicao |
| GET | `/whatsapp/templates` | Lista templates | | GET | `/whatsapp/templates` | Lista templates |
| POST | `/whatsapp/templates` | Cria template | | 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/update/:id` | Atualiza template |
| POST | `/whatsapp/templates/approve-admin/:id` | Aprova template pelo admin | | POST | `/whatsapp/templates/:id/submit-meta` | Envia template para aprovacao da Meta |
| POST | `/whatsapp/templates/reject-admin/:id` | Reprova template pelo admin |
| DELETE | `/whatsapp/templates/:id` | Remove template | | DELETE | `/whatsapp/templates/:id` | Remove template |
## Funcoes importantes ## Funcoes importantes
### `whatsapp.service.ts` ### `whatsapp.service.ts`
- Inicializa cliente WhatsApp Web. - `handleMetaWebhookEvent()` — entry point do webhook, delega para `handleMetaIncomingMessage()`
- Emite QR/status. - `handleMetaIncomingMessage()` — processa mensagem recebida, baixa midia se necessario via `downloadMetaMedia()`
- Lista chats e mensagens. - `downloadMetaMedia()` — busca URL temporaria da Meta e baixa o binario
- Envia mensagens e midias. - `sendMessage()` — envia texto via Meta API
- Dispara roteamento do bot ao receber mensagem. - `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
- Executa abertura ativa com template.
- Nao cria schema de templates em runtime; `whatsapp_templates` deve existir via migrations. ### `whatsapp-config.service.ts`
- Usa `ContactsService` para enriquecer chats com nome, telefone, email, etiqueta e observacao.
- 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` ### `whatsapp-template.service.ts`
- Lista, cria, edita, aprova, reprova e remove templates. - Lista, cria, edita e remove templates.
- Simula aprovacao Meta por tempo para o fluxo de demo. - Sincroniza status com a Meta via `sync-meta`.
- Mantem regra de negocio de template fora do adaptador WhatsApp. - Mantem regra de negocio de template fora do adaptador de canal.
### `whatsapp-template.repository.ts`
- Concentra SQL da tabela `whatsapp_templates`.
- Usa migrations como fonte do schema.
### `attendance-assignment.service.ts` ### `attendance-assignment.service.ts`
- Controla fila e atribuicao em `whatsapp_chat_atribuicoes`. - Controla fila e atribuicao em `whatsapp_chat_atribuicoes`.
- Impede envio quando atendimento ativo aguarda resposta do cliente. - Impede envio quando atendimento ativo aguarda resposta do cliente.
- Roteia conversas por area, fluxo configurado ou arvore do bot. - 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. - 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. | Tipo | Formatos | Limite |
- Mantem o service focado em regra de negocio e orquestracao. |---|---|---|
| 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 |
## Eventos em tempo real ## Eventos em tempo real
O `whatsapp.gateway.ts` usa Socket.IO para notificar o frontend sobre: O `whatsapp.gateway.ts` usa Socket.IO para notificar o frontend sobre:
- novas mensagens; - novas mensagens (texto e midia);
- atualizacoes de chat; - atualizacoes de chat;
- status/QR quando aplicavel. - status de conexao.
## Code review
- `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.
## Proximos passos ## Proximos passos
- Persistir conversas e mensagens no PostgreSQL para auditoria. - Adicionar IA no primeiro atendimento, com configuracao no painel admin para escolher o provedor/modelo.
- Guardar anexos fora do banco, com metadados em `message_attachments` e arquivo em VM Linux, AWS S3, Azure Blob ou SharePoint. - 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. - 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.