Facebook Lead Ads

Anúncios Lead Ads do Facebook capturam leads diretamente dentro do app sem mandar pra site externo (formulário nativo do Facebook). O Syncro integra via webhook com Lead Ads — cada lead capturado vira lead no CRM em ~10s, com mapping de campos, atribuição automática e tags. Esse artigo cobre setup completo.

Pré-requisitos

• Permissão admin.

• Página Facebook (ou Conta Instagram Business linkada) rodando anúncios Lead Ads.

• Feature flag facebook_leadads ativa pro tenant (peça pra suporte se não vê o card).

Conectar Facebook

1. Vá em Configurações → Integrações.
2. Card Facebook Lead Ads (categoria Captação de leads).
3. Clique em Conectar Facebook.
4. Modal abre.
5. Botão Autorizar Facebook.
6. Você é redirecionado pra OAuth Business Login (não OAuth pessoal — exige acesso ao Business Manager).
7. Login Facebook (se não logado).
8. Selecione negócio e páginas que quer dar acesso.
9. Confirma permissões.
10. Redirecionado de volta pro Syncro.
11. Sistema:

• Troca o code por long-lived token (~60 dias).
• Cria OAuthConnection com platform='facebook_leadads'.
• Salva token encriptado.

12. Card vira Conectado com nome do user Facebook.

Configurar conexão de formulário

Após conectar, cada formulário que você quer capturar precisa ser configurado individualmente:

1. Card → Adicionar formulário.
2. Wizard abre.

Passo 1 — Selecionar página

Dropdown lista páginas Facebook que você autorizou:

• Página A.
• Página B.
• Etc.

Selecione a página com os anúncios Lead Ads.

Passo 2 — Selecionar formulário

Após escolher página, sistema busca formulários ativos via Graph API:

• Lista formulários cadastrados (form_id, form_name, question_data).

Selecione o formulário desejado.

Passo 3 — Mapear campos

Sistema lê questões do formulário Facebook e te dá mapping pro lead:

Campo Lead Ads	Campo CRM
full_name	Nome (lead.name)
email	E-mail (lead.email)
phone_number	Telefone (lead.phone)
company_name	Empresa (lead.company)
interesse (custom)	Custom field (Tamanho empresa)
...	...

Pra cada campo do form, dropdown com:

• Não mapear.
• Nome / Telefone / E-mail / Empresa / Valor.
• Custom field:... (lista todos custom fields).

Passo 4 — Configurar destino

• Pipeline: dropdown.
• Etapa inicial: ex: "Novo lead".
• Tags default: ex: lead-ads, instagram-fbads.
• Auto-assign user: dropdown (opcional).
• Permitir duplicatas: toggle (default: false — duplicate detection automático).

5. Clique em Salvar conexão.

Sistema cria FacebookLeadFormConnection no banco e inscreve no webhook leadgen da Meta automaticamente.

Como funciona em produção

1. Cliente vê anúncio

Cliente Facebook/Instagram vê seu anúncio Lead Ads.

2. Clica em "Saiba mais"

Anúncio abre formulário nativo Facebook (sem sair do app).

3. Preenche e envia

Cliente preenche → clica enviar.

4. Webhook chega no Syncro

Meta dispara leadgen webhook pra https://app.syncro.chat/api/webhook/facebook/leadgen:

{
 "object": "page",
 "entry": [{
 "id": "page_id",
 "changes": [{
 "field": "leadgen",
 "value": {
 "leadgen_id": "...",
 "form_id": "...",
 "page_id": "...",
 "created_time": 1735681234
 }
 }]
 }]
}

5. Syncro processa

FacebookLeadgenWebhookController::handle:

1. Valida assinatura HMAC SHA256 (header X-Hub-Signature-256).
2. Job assíncrono ProcessFacebookLeadgenWebhook dispara.
3. Job:

• Busca detalhes do lead via Graph API (/leadgen/{leadgen_id}).
• Aplica field_mapping da FacebookLeadFormConnection.
• Cria lead no Syncro:
• Pipeline + etapa configurados.
• Tags default.
• Auto-assign user.
• Custom fields preenchidos.
• Cria FacebookLeadFormEntry (audit log).

6. Lead aparece no CRM

Em ~10s, lead aparece em /contatos e Kanban.

Anti-duplicação

Por default allow_duplicates=false:

• Sistema busca lead com mesmo telefone OU e-mail.
• Se encontra: não cria duplicado, atualiza tags/notas no lead existente.
• Cria FacebookLeadFormEntry com status='duplicate'.

💡 Dica: deixe allow_duplicates=false por padrão. Cliente que clica em 2 anúncios diferentes não vira 2 leads.

Múltiplas conexões

Você pode ter várias conexões simultâneas:

• Página A + Form 1 → Pipeline Vendas.
• Página A + Form 2 → Pipeline Suporte.
• Página B + Form 3 → Pipeline Marketing.

Cada conexão é independente. Configure quantas precisar.

Teste

Pra validar que está funcionando antes de soltar pro público:

1. Vá em business.facebook.com → Lead Ads Library.
2. Encontre seu form.
3. Clique em Preview ou Test lead.
4. Preencha com dados teste.
5. Submit.
6. Aguarde ~10s.
7. Verifique no Syncro /contatos → lead novo apareceu.

Detecção de duplicatas

Lead duplicado detectado por:

• Telefone exato (após normalização E.164).
• E-mail exato (case-insensitive).
• Nome fuzzy (Levenshtein < 3) + telefone parcial.

Veja Detectar e mesclar duplicatas.

Erros comuns

"Card Facebook Lead Ads não aparece"

Feature flag facebook_leadads desativada pro seu tenant. Peça suporte ativar.

"Lista de páginas vazia"

• Você não autorizou nenhuma no OAuth.
• Reconecte e selecione páginas.

"Lista de formulários vazia"

• Página selecionada não tem formulários Lead Ads ativos.
• Crie primeiro um anúncio Lead Ads no Ads Manager.

"Lead não chega no CRM mesmo após teste"

• Verifique logs (/storage/logs/laravel.log).
• Aguarde até 1min — webhook pode ter delay.
• Confira FacebookLeadFormEntry — apareceu com status='failed'?

"Token expirou — Reconectar"

Token Facebook expira em 60 dias. Sistema não renova automaticamente — você precisa reconectar manualmente.

💡 Dica: marque na agenda pra reconectar antes de vencimento, evita perder leads.

"Permissões removidas pelo cliente"

Se cliente revogou acesso em accountscenter.facebook.com, card vira Reconectar. Reautorize.

Setup técnico (super_admin)

Variáveis no portainer-stack.yml:

FACEBOOK_CLIENT_ID=mesmo_que_whatsapp_cloud
FACEBOOK_CLIENT_SECRET=mesmo
FACEBOOK_LEADGEN_REDIRECT_URI=https://app.syncro.chat/configuracoes/integracoes/facebook-leadads/callback
FACEBOOK_LEADGEN_WEBHOOK_VERIFY_TOKEN=token_aleatorio
FACEBOOK_API_VERSION=v21.0

Webhook configurado no app Meta → URL https://app.syncro.chat/api/webhook/facebook/leadgen. App subscribed em leadgen field das páginas.

Próximos passos

• Pra desconectar, veja Desconectar integração.

Artigos relacionados

• Detectar e mesclar duplicatas
• Auto-criar leads do WhatsApp/Instagram
• Tags de contatos