Manual do Atendimento WhatsApp

1. O que o sistema faz

2. Como funciona

O cliente fala com o número da empresa; a Meta entrega a mensagem ao módulo; o módulo decide quem responde (bot, IA ou atendente) e, quando precisa de dados, consulta o seu sistema.

A integração tem dois sentidos: o seu sistema chama o módulo para enviar mensagens e comunicados (7.1), e o módulo chama o seu sistema para buscar dados durante o atendimento (7.2). Por isso, sim: a sua equipe de TI precisa criar alguns endpoints.

Cada empresa paga a Meta diretamente pelo próprio número (conversas iniciadas pela empresa são cobradas; respostas dentro de 24h, em geral, não).

3. Configuração inicial

3.1 Operador da plataforma (uma vez)

1. Gere os segredos de produção com npm run secrets e preencha o que faltar (credenciais da Meta, chave da Anthropic, SMTP, e-mail de alertas, IPs da VPN). Detalhes no arquivo SECURITY.md.
2. Abra o Console em /admin (só pela VPN). No primeiro acesso entre com a ADMIN_API_KEY e o código do autenticador e cadastre os operadores: cada pessoa recebe login, senha provisória e QR Code do autenticador. A partir daí, a chave não abre mais o console.
3. Em Nova empresa, informe o nome da empresa e o administrador dela. O sistema mostra uma única vez a API key, o segredo dos avisos e a senha provisória: entregue por canais separados.
4. Em Gerenciar → Gerar link de conexão do WhatsApp, envie o link à empresa.

3.2 Empresa

1. Conectar o WhatsApp: abra o link recebido, entre com a conta do Facebook da empresa e escolha o número. O pagamento das mensagens fica na conta da própria empresa na Meta.
2. Primeiro acesso ao painel (/editor): entre com a senha provisória, defina uma nova senha e ative a verificação em duas etapas (Google ou Microsoft Authenticator). Guarde os 10 códigos de recuperação.
3. Configurações: horário de atendimento, aviso de privacidade (LGPD), IA ligada ou não, tempo de sessão.
4. Integrações: peça à TI os endereços dos endpoints (seção 7.2) e cadastre-os, com a credencial de acesso se o sistema exigir token.
5. Fluxos: clique em Usar modelo de faturas, informe o endereço base do seu sistema, teste no Simulador e clique em Ativar.
6. Usuários: cadastre os atendentes. Cada um troca a senha e ativa o 2FA no primeiro acesso.

4. Usando o painel

5. Fluxos do bot

Um fluxo é uma sequência de passos. Os textos aceitam variáveis, por exemplo {{contact.firstName}} (nome do cliente no WhatsApp) e {{customer.nome}} (nome vindo do seu sistema).

O cliente pode digitar a qualquer momento menu (volta ao início), atendente (vai para a fila) ou SAIR (deixa de receber comunicados).

6. Ensinando a IA

Não é preciso treinar um modelo (fine-tuning). A IA aprende o jeito e o conteúdo da sua empresa por dois caminhos, que valem na hora:

6.1 Instruções para a IA

Em Configurações → Instruções para a IA, descreva como ela deve se comportar. Bons exemplos:

Você é o assistente da Energia Exemplo. Seja cordial e objetivo, em frases curtas.
Trate o cliente por "você". Não prometa prazos de religação: informe o prazo da base de conhecimento.
Para reclamações sobre cobrança indevida, transfira para um atendente.
Horário de atendimento humano: segunda a sexta, 8h às 18h.

6.2 Base de conhecimento

Em Conhecimento, envie os documentos que a IA deve consultar: tarifas, prazos, perguntas frequentes, regras de religação, formas de pagamento. Dicas:

• Um assunto por documento, com títulos claros (ex.: "Prazos de religação").
• Prefira texto a imagens: a IA não lê texto dentro de figuras.
• Atualize quando a regra mudar: a IA usa sempre a versão atual.
• Teste no Simulador fazendo as perguntas que os clientes fazem.

6.3 O que a IA pode e não pode

Documentos com senhas, CPFs ou instruções para "enganar" a IA são recusados no envio. Cada empresa tem um limite diário de respostas da IA, definido pela plataforma.

7. Integração com o seu sistema

Para a equipe de TI. Endereço base: o domínio do módulo (ex.: https://atendimento.suaempresa.com.br). Autenticação das chamadas ao módulo: cabeçalho x-api-key com a API key da empresa (gerada no Console e girada em Configurações). Números sempre com DDI, só dígitos: 5562999990000.

7.1 Enviar mensagens (o seu sistema chama o módulo)

Exemplos:

POST /v1/contacts/opt-in
x-api-key: wak_...
{ "waIds": ["5562999990000"], "source": "contrato-assinado" }

POST /v1/messages
{ "to": "5562999990000", "type": "template",
  "content": { "name": "aviso_fatura", "language": { "code": "pt_BR" },
               "components": [{ "type": "body", "parameters": [
                 { "type": "text", "text": "Maria" }, { "type": "text", "text": "R$ 312,40" } ] }] } }

POST /v1/messages        (cliente escreveu há menos de 24h)
{ "to": "5562999990000", "type": "text", "content": { "body": "Sua religação foi concluída." } }

POST /v1/broadcasts
{ "to": ["5562999990000", "5562988887777"], "type": "template",
  "content": { "name": "manutencao_programada", "language": { "code": "pt_BR" } },
  "reference": "manutencao-out-2026" }

Respostas de erro mais comuns: 403 contato sem opt-in ou que pediu para sair · 422 fora da janela de 24h (use template) · 429 limite de envio por minuto ou por dia atingido.

7.2 Endpoints que o seu sistema expõe (o módulo chama o seu sistema)

Durante o atendimento, o módulo faz POST nos endereços cadastrados em Integrações. O modelo de faturas usa três:

Toda chamada tem este formato:

POST https://seu-sistema/whatsapp/segunda-via
Authorization: Bearer ...          (se você cadastrou uma credencial)
x-timestamp: 1792268000
x-signature-v2: t=1792268000,sha256=<HMAC-SHA256 de "x-timestamp.corpo" com o segredo dos avisos>
{ "action": "segunda_via",
  "input": { "faturaId": "f-2026-10" },
  "contact": { "waId": "5562999990000", "name": "Maria" },
  "customer": { "id": "c1", "nome": "Maria Silva" } }

• Valide a assinatura e recuse chamadas com x-timestamp de mais de 5 minutos.
• Use o customer.id para buscar os dados, nunca um CPF vindo do texto: assim um cliente não acessa dados de outro.
• O pdfUrl precisa ser HTTPS público, de preferência um link temporário (expira em minutos).
• Responda em até 15 segundos (ajustável em cada ação, de 1 a 60). 404 = não encontrado (o fluxo segue por "se falhar"); outros erros = o bot avisa e chama um atendente.
• Endereços internos (rede local, localhost) são bloqueados por segurança: o endpoint precisa ser HTTPS acessível pela internet, protegido pelo token e pela assinatura.

Você pode criar outras ações (consumo, religação, protocolo) em Integrações: a IA as usa automaticamente, guiada pela descrição de cada uma. Marque "exige cliente identificado" em toda ação que devolve dados pessoais.

7.3 Verificação de identidade

Para não entregar dados a quem só sabe o CPF de outra pessoa, o módulo confere quem está falando, depois que o seu sistema encontra o CPF/CNPJ:

Para isso, o identificar_cliente deve devolver:

{ "id": "c1", "nome": "Maria Silva",
  "telefones": ["5562999990000"],
  "verificacao": { "dataNascimento": "1985-03-14", "nomeMae": "Ana Souza Silva",
                   "nomeCompleto": "Maria Aparecida Silva", "cep": "74000-000",
                   "email": "maria@exemplo.com" } }

Telefones em qualquer formato (com ou sem DDI, 9º dígito ou máscara). As respostas certas não ficam guardadas (só uma impressão digital delas), e as respostas do cliente não passam pela IA. Telefones e dados de verificação são descartados depois da conferência.

7.4 Avisos de eventos (opcional)

Se a empresa informar uma URL de avisos, o módulo envia POST a cada mensagem recebida e a cada mudança de situação de envio (message.received, message.sent, message.delivered, message.read, message.failed), com a mesma assinatura do item 7.2 e o cabeçalho x-event-id. Ignore eventos com id repetido: o módulo tenta de novo por até 8 vezes se o seu sistema estiver fora do ar.

8. Inbox dos atendentes

1. Entre em /inbox com e-mail, senha e código do autenticador.
2. Na fila estão as conversas que pediram atendente. Clique numa e em Assumir.
3. Responda pelo campo de mensagem; use o clipe para enviar arquivos (imagens, PDF, documentos).
4. Ao terminar, Encerrar (a próxima mensagem do cliente abre uma nova conversa) ou Devolver ao bot.

Depois de 24h sem mensagem do cliente, o WhatsApp não permite texto livre: aparece um aviso, e só é possível enviar um template aprovado. Arquivos recebidos passam por antivírus antes de abrir.

9. Segurança e LGPD

Desligar a verificação pelo número exige administrador e avisa os demais por e-mail. Não é recomendado.

10. Problemas comuns

11. Integração com a Meta (operador da plataforma)

Feita uma vez, pela empresa que opera a plataforma. Depois disso, cada empresa cliente só clica no link de conexão (seção 3.2). Tempo total: de 1 a 4 semanas, quase tudo esperando aprovações da Meta.

A Meta muda nomes e posições de menu com frequência. Se uma tela estiver diferente, procure pelo termo em negrito na busca do painel da Meta ou na documentação oficial do WhatsApp.

Etapa 1 — Conta empresarial (Meta Business) e verificação

1. Acesse business.facebook.com com um perfil pessoal do Facebook de um responsável da empresa (use um perfil real e protegido com 2FA: ele será administrador de tudo).
2. Crie o Portfólio empresarial com o nome jurídico da empresa, e-mail corporativo e site.
3. Vá em Configurações → Central de segurança → Verificação da empresa e clique em Iniciar verificação.
4. Informe razão social, CNPJ, endereço e telefone exatamente como no cartão CNPJ. Envie o documento pedido (cartão CNPJ ou contrato social) e confirme pelo método oferecido (e-mail do domínio, telefone ou documento).
5. Ative a autenticação de dois fatores obrigatória para todos os administradores do portfólio.

Dica: o site e o e-mail precisam ser do mesmo domínio da empresa. Divergência de nome ou endereço é a causa mais comum de recusa.

Etapa 2 — Criar o app

1. Acesse developers.facebook.com → Meus apps → Criar app.
2. Escolha o caso de uso de WhatsApp (ou tipo Empresa/Business) e vincule ao portfólio da etapa 1.
3. No app, adicione o produto WhatsApp (se não vier adicionado).
4. Em Configurações do app → Básico, preencha: ícone, URL da Política de Privacidade, URL dos Termos de Serviço, categoria e e-mail de contato. Sem a política de privacidade publicada, o App Review é recusado.
5. Copie o ID do app e a Chave secreta do app (botão Mostrar) para o .env.production:

   META_APP_ID=123456789012345
   META_APP_SECRET=a1b2c3...   (guarde no cofre; nunca compartilhe)

Etapa 3 — Publicar o sistema com HTTPS

A Meta só envia mensagens para endereço público com HTTPS. Siga SECURITY.md e use o deploy/nginx.conf. Confira antes de continuar:

https://SEU-DOMINIO/health        → {"status":"ok"}

Etapa 4 — Webhook (para receber as mensagens)

1. No app: WhatsApp → Configuração (ou Configuration) → seção Webhook → Editar.
2. URL de callback: https://SEU-DOMINIO/webhooks/meta
3. Token de verificação: o valor de META_WEBHOOK_VERIFY_TOKEN do .env.production (gerado pelo npm run secrets).
4. Clique em Verificar e salvar. Se falhar: o sistema não está acessível pela internet, o token está diferente ou o HTTPS é inválido.
5. Em Campos do webhook, clique em Gerenciar e assine o campo messages.

O sistema recusa qualquer aviso que não venha assinado com a sua META_APP_SECRET. Se as mensagens chegam na Meta mas não no painel, confira se a chave secreta no .env.production é a do mesmo app.

11.1 Etapa 5 — Testar com o número de teste (antes de qualquer aprovação)

1. No app: WhatsApp → Configuração da API (ou API Setup). A Meta já oferece um número de teste gratuito.
2. Em Para, cadastre até 5 celulares que vão testar (cada um confirma por código no WhatsApp).
3. Copie o Identificador do número de telefone (Phone number ID) e o Identificador da conta do WhatsApp Business (WABA ID).
4. Gere um token permanente: no portfólio, Configurações → Usuários do sistema → Adicionar (função Administrador), atribua o app e a conta do WhatsApp, e em Gerar token marque whatsapp_business_messaging e whatsapp_business_management, validade Nunca. O token temporário da tela de API expira em 24h: não use em produção.
5. No Console da plataforma (/admin), crie uma empresa de teste e informe esses dados por PATCH /admin/tenants/<id> (ou peça à TI):

   { "wabaId": "...", "phoneNumberId": "...", "accessToken": "EAAG..." }

6. Do celular cadastrado, mande "oi" para o número de teste. A conversa deve aparecer no bot e na inbox. Teste o fluxo de faturas, a IA e o atendimento humano.

Etapa 6 — Embedded Signup (para cada empresa conectar o próprio número)

1. No app, adicione o produto Login do Facebook para Empresas (Facebook Login for Business).
2. Em Login do Facebook para Empresas → Configurações, adicione o domínio em Domínios permitidos para o SDK JavaScript e URIs de redirecionamento OAuth válidos: https://SEU-DOMINIO/.
3. Em Configurações → Criar configuração: tipo de login WhatsApp Embedded Signup, tipo de token Token de acesso do usuário do sistema, ativos Contas do WhatsApp Business, permissões whatsapp_business_messaging e whatsapp_business_management.
4. Copie o ID da configuração para o .env.production: META_ES_CONFIG_ID=...
5. Teste: no Console, Gerenciar → Gerar link de conexão do WhatsApp, abra o link e conecte um número. (Enquanto o app não for aprovado, só pessoas com função no app conseguem concluir.)

11.2 Etapa 7 — App Review e Tech Provider

Para que outras empresas conectem o número delas pelo seu app, a Meta precisa aprovar o acesso avançado às permissões e o cadastro como Tech Provider (provedor de tecnologia).

1. No app: Revisão do app → Permissões e recursos. Solicite Acesso avançado a whatsapp_business_messaging e whatsapp_business_management (e business_management, se pedido).
2. Para cada permissão, descreva o uso (texto sugerido abaixo) e envie um vídeo.
3. Conclua o cadastro de Tech Provider quando a Meta solicitar (aparece no painel do app ou na seção WhatsApp; exige a empresa verificada da etapa 1).
4. Acompanhe em Revisão do app → Solicitações. Se recusarem, a Meta diz o motivo; ajuste e reenvie.

Texto sugerido para a descrição do uso:

Somos uma plataforma de atendimento pelo WhatsApp para empresas de energia e serviços.
Cada empresa cliente conecta o próprio número pelo Embedded Signup e paga a Meta diretamente.
whatsapp_business_management: usamos para listar e criar modelos de mensagem (templates) da
conta do cliente e inscrever nosso app nos webhooks da conta conectada.
whatsapp_business_messaging: usamos para enviar e receber mensagens em nome da empresa cliente:
respostas do atendimento automático (2ª via de fatura), atendimento humano pela nossa inbox e
comunicados para clientes que deram consentimento (opt-in), com opção de saída (SAIR).
Os dados ficam criptografados, com controle de acesso por usuário e 2FA.

Roteiro do vídeo (gravação de tela, 3 a 5 minutos, sem cortes nos momentos-chave, áudio ou legendas em inglês ajudam):

Dicas: use dados fictícios (o ERP de teste do sistema serve), mostre a URL do navegador, não exiba tokens nem senhas na tela e use o número de teste da etapa 5.

Etapa 8 — Publicar o app

1. Com o App Review aprovado, no topo do painel do app mude o Modo do app de Desenvolvimento para Ao vivo (Live).
2. Teste o link de conexão com uma empresa cliente real.
3. Pronto: a partir daqui, para cada nova empresa basta o Console (seção 3.1).

Erros comuns na Meta