# Integração do ProfEdu com WhatsApp

## Arquitetura recomendada

Separe o protótipo visual do canal de mensagens. O fluxo de negócio deve receber uma mensagem normalizada e devolver uma resposta normalizada. Assim, o mesmo bot funciona com WhatsApp Cloud API ou Evolution API.

```text
WhatsApp → webhook/adaptador → motor do ProfEdu → banco de progresso → painel admin
                                      ↓
                              adaptador de envio
```

**Nunca coloque tokens no HTML, no JavaScript do navegador ou no Git.** Use variáveis de ambiente no backend.

## Opção A — WhatsApp Cloud API oficial

A documentação da Meta descreve a criação de um app com WhatsApp, a conexão a uma conta de mensagens, um `phone_number_id`, token e um endpoint de webhook [1]. Para produção, use um token permanente de system user, com as permissões adequadas, armazenado no servidor.

### Passos

1. Criar/usar um portfólio empresarial da Meta e um app com o caso de uso WhatsApp.
2. Conectar uma conta do WhatsApp Business e um número dedicado.
3. Guardar no servidor: `META_ACCESS_TOKEN`, `META_PHONE_NUMBER_ID`, `META_VERIFY_TOKEN` e `META_APP_SECRET`.
4. Criar `GET /webhooks/whatsapp` para responder ao desafio de verificação.
5. Criar `POST /webhooks/whatsapp` para processar mensagens recebidas e status enviados.
6. Validar assinatura quando aplicável, deduplicar pelo ID da mensagem e responder rapidamente com HTTP 200.
7. Enviar mensagens pelo endpoint Graph da versão configurada, usando texto livre dentro da janela de atendimento ou templates aprovados quando necessário.
8. Registrar o telefone com hash/ID interno, a trilha, o estado da conversa, respostas, acertos e timestamps.

A Meta informa que webhooks podem transportar mensagens recebidas e status de mensagens enviadas; falhas diferentes de HTTP 200 podem gerar novas tentativas, então a aplicação deve ser idempotente [2].

## Opção B — Evolution API

A Evolution API é uma API REST de código aberto que suporta conexões baseadas em WhatsApp Web/Baileys e também integração com WhatsApp Cloud API [3]. A opção Baileys é prática para protótipo, mas não é o mesmo que a API oficial da Meta e deve ser avaliada quanto a estabilidade, políticas e risco operacional.

### Passos

1. Hospedar a Evolution API com HTTPS, banco e chave de API.
2. Criar uma instância exclusiva para o grupo/projeto.
3. Conectar a instância por QR Code ou configurar o provedor Cloud.
4. Configurar o webhook para eventos de mensagens recebidas.
5. No adaptador, extrair telefone, nome, texto, ID do evento e timestamp.
6. Enviar respostas pelo endpoint de texto da instância, mantendo a chave apenas no backend.
7. Deduplicar eventos, registrar logs e monitorar o estado da instância.

## Contrato interno sugerido

```ts
type IncomingMessage = {
  provider: 'meta' | 'evolution';
  externalMessageId: string;
  phone: string;
  name?: string;
  text: string;
  receivedAt: string;
};

type OutgoingMessage = {
  phone: string;
  text: string;
  correlationId?: string;
};
```

O motor deve operar em cima desse contrato, não em cima do formato específico do provedor.

## Estado da conversa

Persistir, no mínimo:

- `student_id`, telefone normalizado e nome;
- `track` ou cargo escolhido;
- `state`: `MENU`, `CHOOSING_TRACK`, `WAITING_ANSWER`, `REVIEW`, `PERFORMANCE`;
- questão exibida e alternativa escolhida;
- acertos, tentativas, último contato e progresso por módulo;
- IDs externos das mensagens processadas.

## Painel administrativo

O painel local em `admin.html` usa dados demonstrativos. Para produção, substituir `students` e `activity` em `admin.js` por chamadas autenticadas, por exemplo `GET /api/admin/students` e `GET /api/admin/activity`. Nunca disponibilizar dados pessoais sem controle de acesso.

## Checklist de produção

- [ ] Consentimento e opt-out (`SAIR`) implementados.
- [ ] Número dedicado e política de atendimento definidas.
- [ ] Tokens em secret manager/variáveis de ambiente.
- [ ] HTTPS e autenticação do painel.
- [ ] Idempotência e fila para webhooks.
- [ ] Logs sem expor conteúdo sensível desnecessário.
- [ ] Backup e retenção de dados definidos.
- [ ] Aviso de privacidade e base legal avaliados.
- [ ] Testes de mensagens, duplicidade, reenvio e indisponibilidade.

## Referências

[1]: https://developers.facebook.com/documentation/business-messaging/whatsapp/get-started "WhatsApp Cloud API Get Started — Meta"

[2]: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview "WhatsApp webhooks — Meta"

[3]: https://github.com/EvolutionAPI/evolution-api "Evolution API — repositório oficial"