Embed — Incorporar Leads e Notificações em iframes

O LeadFilter permite incorporar as páginas de Leads (chat) e Notificações em outros sistemas via iframe. Isso é útil para integrar o chat e as notificações em CRMs, dashboards ou portais de clientes.

Passo a passo para integrar

1. Criar o token no painel LeadFilter

1. Faça login no painel LeadFilter
2. Vá em Settings (Configurações) → expanda o menu → Embed → Tokens
3. Clique em Criar token
4. Preencha:
   • Nome: ex. "Integração CRM Cliente X"
   • Domínios permitidos: um por linha, ex. https://app.seudominio.com ou https://*.seudominio.com para subdomínios
   • Escopos: marque Leads e/ou Notificações conforme o que precisar incorporar
   • Expiração (opcional): data em que o token deixa de funcionar
5. Clique em Criar e copie o token imediatamente — ele não será exibido novamente

2. Expor o token no seu backend (seguro)

O token nunca deve aparecer no HTML ou JavaScript público. Crie um endpoint no seu backend que retorne o token apenas para usuários autenticados:

// Exemplo: Node.js/Express
app.get('/api/leadfilter-embed-token', requireAuth, async (req, res) => {
  // Busque o token do seu banco, variável de ambiente, etc.
  const token = process.env.LEADFILTER_EMBED_TOKEN;
  res.json({ token });
});

3. Adicionar o iframe na sua página

Inclua o iframe no HTML da sua aplicação:

<iframe
  id="leadfilter-embed"
  src="https://app.leadfilter.ai/embed/leads"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Substitua app.leadfilter.ai pela URL do seu ambiente (ex: app.leadfilter.online).

4. Enviar o token via postMessage

Quando o iframe carregar, ele exibirá "Aguardando autenticação...". Seu JavaScript deve obter o token do backend e enviá-lo:

<script>
  const iframe = document.getElementById('leadfilter-embed');
  iframe.onload = () => {
    fetch('/api/leadfilter-embed-token')
      .then((r) => r.json())
      .then(({ token }) => {
        iframe.contentWindow.postMessage(
          { type: 'LEADFILTER_AUTH', token },
          'https://app.leadfilter.ai'
        );
      });
  };
</script>

O segundo argumento de postMessage deve ser a URL exata do LeadFilter (origem do iframe) por segurança.

5. (Opcional) Escutar eventos do embed

Para saber quando o embed está pronto ou se houve erro:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'LEADFILTER_READY') {
    console.log('Embed carregado com sucesso');
  }
  if (event.data?.type === 'LEADFILTER_ERROR') {
    console.error('Erro:', event.data?.message);
  }
});

---

Segurança

• Tokens de embed: cada token tem domínios permitidos (whitelist) e escopos (leads, notifications)
• Validação de origem: o backend valida o header Origin ou Referer contra os domínios configurados
• Token exibido uma vez: ao criar o token, copie-o imediatamente — não será exibido novamente

Configuração no painel

1. Acesse Settings > Embed (requer role ADMIN)
2. Clique em Criar token
3. Preencha:
   • Nome: identificação (ex: "Integração CRM Cliente X")
   • Domínios permitidos: um por linha (ex: https://app.cliente.com, https://*.cliente.com)
   • Escopos: Leads, Notificações ou ambos
   • Expiração (opcional): data/hora em que o token deixa de funcionar
4. Copie o token gerado — ele não será exibido novamente

Integração

URLs de embed

• Leads (chat): https://app.leadfilter.ai/embed/leads
• Notificações: https://app.leadfilter.ai/embed/notifications

Substitua app.leadfilter.ai pela URL do seu ambiente.

Fluxo de autenticação (postMessage — recomendado)

O iframe exibe "Aguardando autenticação..." até receber o token. O site pai deve obter o token em seu backend (nunca exponha o token em HTML público) e enviá-lo via postMessage:

<iframe
  id="leadfilter-embed"
  src="https://app.leadfilter.ai/embed/leads"
  width="100%"
  height="600"
  frameborder="0">
</iframe>
<script>
  const iframe = document.getElementById('leadfilter-embed');
  iframe.onload = () => {
    // Obtenha o token do seu backend (nunca exponha no frontend público)
    fetch('/api/leadfilter-embed-token')
      .then((r) => r.json())
      .then(({ token }) => {
        iframe.contentWindow.postMessage(
          { type: 'LEADFILTER_AUTH', token },
          'https://app.leadfilter.ai'
        );
      });
  };
</script>

Eventos postMessage (iframe → parent)

O iframe pode enviar eventos ao parent:

Tipo	Descrição
LEADFILTER_READY	Autenticação concluída, conteúdo carregado
LEADFILTER_ERROR	Erro na autenticação (payload: { message: string })

Exemplo para escutar:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'LEADFILTER_READY') {
    console.log('Embed pronto');
  }
  if (event.data?.type === 'LEADFILTER_ERROR') {
    console.error('Erro no embed:', event.data?.message);
  }
});

Token via URL (fragmento)

Alternativa para casos simples: passe o token no fragmento da URL:

https://app.leadfilter.ai/embed/leads#token=lf_embed_xxx

Para embed cross-origin, inclua a origem do site pai para validação:

https://app.leadfilter.ai/embed/leads#token=lf_embed_xxx&origin=https://app.cliente.com

O fragmento não é enviado no Referer, mas fica visível no cliente. Use com cuidado — evite em páginas públicas.

API de troca de token

O iframe chama internamente:

POST /api/auth/embed-token
Content-Type: application/json

{ "embedToken": "lf_embed_xxx" }

Quando o iframe é incorporado em outro domínio, o iframe envia a origem do parent (via postMessage) no body da requisição. O backend valida essa origem contra os domínios permitidos do token.

Personalização (tema)

Em Settings > Embed > Personalização (tema) você pode customizar a aparência dos iframes:

• Cores: primária, secundária, fundo, superfície, texto, bordas, destaque
• Tipografia: família da fonte, tamanho base
• Layout: raio das bordas, URL do logo

As alterações são aplicadas em tempo real em todos os embeds do tenant.

---

Escopos

Escopo	Acesso
leads	Página de leads (chat), APIs de leads
notifications	Página de notificações, APIs de lead-notifications e notification-history

Um token pode ter um ou ambos os escopos.