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 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 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`

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 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.
Consulta AgentPresenceService antes de atribuir atendimento a um usuario.

Midia — tipos e limites aceitos em `send-media`

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

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

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.

Modulo WhatsApp

Responsabilidade

Endpoints

Funcoes importantes

whatsapp.service.ts

whatsapp-config.service.ts

media-storage.service.ts

whatsapp-template.service.ts

attendance-assignment.service.ts

Midia — tipos e limites aceitos em send-media