Usar WhatsApp API integrada

WhatsApp API integrada é a conexão oficial usada quando a operação precisa de mais estabilidade, templates aprovados pela Meta e envio de primeira mensagem…

WhatsApp API integrada é a conexão oficial usada quando a operação precisa de mais estabilidade, templates aprovados pela Meta e envio de primeira mensagem fora da janela comum de atendimento.

Nos planos Sofia, ela não substitui automaticamente o WhatsApp por QR Code. Nos planos CRM, o produto base funciona sem WhatsApp e o canal só aparece depois da contratação e ativação do add-on oficial.

Antes de começar

Diferença entre QR Code e API integrada

No modo Evolution QR Code, o WhatsApp funciona como um aparelho conectado. Ele é rápido para começar, mas depende da sessão do celular/WhatsApp Web e pode precisar de reconexão por QR Code.

Na WhatsApp API integrada, o número fica conectado pela infraestrutura oficial da Meta. Esse modo permite trabalhar com templates aprovados para primeira mensagem, CRM e follow-ups fora da janela de 24h.

Nos planos Sofia, os dois caminhos podem ficar cadastrados. Quando você troca de provider no dashboard, a conta oficial e a instância por QR Code permanecem preservadas para rollback. O add-on dos planos CRM opera somente pela API oficial e não usa Evolution como fallback.

Como funcionam o acesso e os custos

WhatsApp API oficial disponível mediante análise. Existem dois contratos:

Custos variáveis cobrados pela Meta, quando existirem, ficam na própria BM/WABA do cliente. Isso inclui mensagens de template e outras categorias cobradas pela Meta conforme regra vigente, país e categoria da mensagem.

Na prática:

Preparar a Meta antes de conectar

  1. Acesse business.facebook.com/settings.
  2. Selecione a BM ou portfólio empresarial correto.
  3. Abra a área de pagamentos/cobrança da Meta.
  4. Adicione um cartão ou método de pagamento aceito.
  5. Confirme se a conta WhatsApp ou WABA não mostra alerta de billing.
  6. Se a Meta pedir verificação, abra Centro de Segurança ou Informações da empresa.
  7. Inicie a verificação e envie os documentos solicitados.
  8. Aguarde o retorno da Meta antes de escalar volume ou depender de recursos avançados.

Os nomes dos menus da Meta podem variar por idioma e tipo de conta. O ponto importante é: pagamento primeiro, verificação depois quando a Meta exigir.

Solicitar e conectar pelo dashboard

  1. Abra Integrações.
  2. Encontre o card WhatsApp API oficial.
  3. Clique em Solicitar WhatsApp API.
  4. Informe os dados básicos do responsável, número, empresa e situação da BM e da forma de pagamento Meta.
  5. Confirme que os custos variáveis da Meta ficam na BM/WABA da empresa.
  6. Envie e aguarde a análise da equipe ImobAI.
  7. Em um plano CRM, clique em Ativar add-on, confira o proporcional e conclua o pagamento pelo Asaas. Em um plano Sofia, avance direto para a conexão depois da aprovação.
  8. Clique em Conectar WhatsApp API.
  9. Conclua a autorização da Meta na tela aberta.
  10. Volte ao dashboard e confira se a conta oficial aparece como conectada.
  11. Em um plano Sofia, clique em Usar WhatsApp API somente quando estiver pronto para trocar o provider ativo.

Conectar a conta oficial não envia mensagens automaticamente. Trocar o provider também não reprocessa filas e não dispara follow-up sozinho.

Criar e aprovar templates

  1. Abra Modelos WhatsApp API.
  2. Crie um modelo ou use um modelo-base.
  3. Escolha o uso: primeira mensagem CRM, campanha ou follow-up.
  4. Escreva o texto com variáveis simples, como nome, produto e empresa.
  5. Preencha exemplos reais para cada variável.
  6. Salve como rascunho.
  7. Envie para aprovação da Meta.
  8. Aguarde o status aprovado antes de vincular em fluxos automáticos.

Templates são aprovados por conta WhatsApp/BM. Um modelo-base pode ser reaproveitado, mas cada cliente precisa aprovar na própria conta oficial.

Vincular templates em CRM, campanha e follow-up

Depois que o modelo estiver aprovado:

  1. Abra Configurações para definir modelos padrão de primeira mensagem CRM e follow-ups.
  2. Abra Campanhas para escolher modelos específicos de uma campanha.
  3. Confira se as variáveis obrigatórias existem no lead, campanha ou produto.
  4. Reprocesse somente bloqueios elegíveis, quando houver, pela área de filas ou integrações.

Se a janela de 24h estiver fechada e não houver template aprovado/vinculado, a Sofia bloqueia o envio automático em vez de improvisar uma mensagem livre.

Automação por regra e atendimento Sofia

Nos planos CRM com add-on, a automação é determinística: o operador escolhe um modelo aprovado, define público, limites e horários, confere a prévia e confirma o disparo. Esse fluxo não usa LLM, RAG, voz ou geração de texto e não libera a Sofia.

Nos planos Sofia, o atendimento por IA continua sendo uma capacidade separada. A Sofia pode responder dentro das permissões do canal e do tenant, enquanto primeira mensagem e retomada fora da janela continuam dependendo de templates aprovados. Ativar uma regra não ativa a Sofia, e pausar a Sofia não cancela uma regra que já foi confirmada.

Voltar para Evolution QR Code

Este procedimento existe somente para planos Sofia que já possuem uma instância por QR Code preservada. Planos CRM com add-on oficial não usam Evolution.

  1. Abra Integrações.
  2. No card WhatsApp API integrada, clique em Voltar para Evolution.
  3. Confirme a troca.
  4. Se o Evolution estiver desconectado, clique em Reconectar Evolution por QR Code.
  5. Confira o status do WhatsApp antes de retomar filas.

O rollback preserva a conta oficial e os modelos. Você pode voltar a usar a API integrada depois, sem refazer todo o cadastro, desde que a conta continue pronta.

Problemas comuns

A Meta bloqueou envio por falta de pagamento

Cadastre ou atualize o método de pagamento na BM/Meta. Depois volte ao dashboard e tente sincronizar ou enviar novamente.

A BM não está verificada

Alguns recursos e limites podem exigir verificação. Inicie a verificação no Business Manager e use dados iguais aos documentos da empresa.

O template foi rejeitado

Revise promessas, termos comerciais, variáveis e categoria. Crie uma versão mais clara e envie novamente.

A primeira mensagem não saiu

Confira se existe template aprovado e vinculado para aquele fluxo. Fora da janela de 24h, mensagem livre não substitui template.

O Evolution está desconectado

Use Reconectar Evolution por QR Code antes de voltar para o provider por QR. Não retome fila acumulada sem confirmar o status conectado.

Referências oficiais

Veja também