P8.1 · Grupo VIP — provisionamento de instância por tenant
Depende de P0.3 e P2.1. Skill obrigatória: `/evolution-api-ecomsmart`.
Leia antes de escrever código
Grupo de WhatsApp não existe na API Oficial da Meta. Toda a funcionalidade de grupo (listar, entrar, mandar mensagem, moderar) só existe pela camada não-oficial — no nosso caso, a Evolution API self-hosted que a EcomSmart já opera para relatórios internos. Isso significa:
- Nunca escrever "WhatsApp API Oficial" em nenhuma tela ou copy do Grupo VIP. É a única exceção de todo o catálogo. Use "conectado ao seu WhatsApp" ou "via QR Code".
- Risco de banimento é real e mais agressivo em grupo do que em mensagem individual. Recomende ao lojista um número secundário, nunca o principal.
- A instância corporativa
EAPI - DURAES(usada para os relatórios internos da EcomSmart) nunca deve compartilhar webhook ou fluxo com as instâncias de cliente criadas aqui.
O prompt
Implemente o provisionamento de instância WhatsApp por loja, no app grupovip do repo radar.
1. Modelos
- InstanciaWhatsapp:
loja,nome_instancia(padrãotenant-<loja_id>),status(aguardando_qr, conectada, desconectada, banida),numero_conectado,qr_code_atual,conectada_em,ultima_atividade_em. - Grupo:
instancia,jid(sempre normalizado terminando em@g.us),nome,qtd_membros,sincronizado_em. - MembroGrupo:
grupo,jid_membro,entrou_em,saiu_em(nulo se ainda no grupo),mensagens_30d(contador de engajamento).
2. Provisionamento
Endpoint que, ao lojista assinar o plano, chama a Evolution API do servidor compartilhado:
POST {evolution}/instance/create
{ "instanceName": "tenant-<loja_id>", "qrcode": true }
- Grava o QR code retornado e exibe na tela até o lojista escanear.
- Poll ou webhook de
connection.updatepara detectaropen(conectado) e atualizarInstanciaWhatsapp.status. - Se a instância cair (
close), notificar o lojista por e-mail e marcardesconectada— nunca tentar reconectar sozinho sem novo QR code, isso é o que mais derruba número.
3. Sincronização de grupos
Após conectar, GET {evolution}/group/fetchAllGroups/{instancia}?getParticipants=false (endpoint documentado na skill). Lojista escolhe qual grupo é o "VIP" a gerenciar — nunca gerenciar todos os grupos da conta dele automaticamente, só o(s) explicitamente selecionado(s), respeitando o limite do plano (1 no Essencial, 5 no Pro).
4. Registro de webhooks
Configure o webhook da instância para receber:
group-participants-update→ grava entrada e saída emMembroGrupo(usado por P8.2 para boas-vindas e analytics)messages-upsert→ conta engajamento (usado por P8.2 para moderação e ranking)
5. Limite de taxa
Nenhuma ação de escrita na Evolution (enviar mensagem, mudar assunto do grupo, atualizar participante) pode sair sem passar por um limitador central, com folga generosa e documentada em grupovip/README.md. Escreva o limitador antes de qualquer chamada de escrita — não deixe para depois.
6. Capacidade
Cada instância ativa consome memória o tempo todo no servidor Evolution compartilhado (~300 MB). Antes de provisionar um lote grande de clientes novos, verifique a capacidade disponível no servidor — não provisione sem checar.
Critérios de aceite
- Provisionamento real de uma instância de teste, com QR code exibido e conexão confirmada, usando um número secundário (nunca o principal de produção)
- Webhooks de
group-participants-updateemessages-upsertchegando e gravando corretamente - Teste do limitador de taxa recusando uma rajada de chamadas
- Teste de que a instância corporativa
EAPI - DURAESnunca é usada nem referenciada neste fluxo - Teste de que o limite de grupos por plano é respeitado (Essencial recusa o segundo grupo)
grupovip/README.mddocumentando o limite de taxa escolhido e por quê
Secret radar-evolution com a URL e o token admin do servidor Evolution compartilhado. Peça a mim — não invente.