Ação — extrair dados com IA

A ação ai_extract_fields é uma das mais poderosas do Syncro. Em vez de você (ou seu vendedor) manualmente copiar dados que o cliente menciona na conversa pra dentro do CRM, a IA lê o histórico e preenche os campos vazios sozinha. Email mencionado? Captura. Empresa? Captura. Valor potencial? Captura.

É a forma mais inteligente de enriquecer leads automaticamente sem comprometer atendimento humano.

Pré-requisitos

• WhatsApp conectado (a IA lê conversa WhatsApp principalmente).
• Tokens IA disponíveis na quota mensal (consome tokens). Veja Quota de tokens.
• Permissão de admin ou manager.

Como funciona

A action segue um fluxo robusto:

1. Automação dispara (ex: gatilho message_received).
2. Sistema enfileira o ExtractLeadDataJob (assíncrono, fila ai).
3. Job carrega a conversa WhatsApp mais recente do lead.
4. Monta transcript das últimas N mensagens.
5. Cria prompt estruturado com schema dos campos a extrair.
6. Chama LLM (geralmente OpenAI gpt-4o-mini) com structured outputs.
7. LLM retorna JSON com valores encontrados.
8. Aplica os valores nos campos do lead — NUNCA sobrescreve campos já preenchidos.
9. Registra evento na timeline do lead: "IA extraiu: email=[email protected], empresa=ACME".
10. Loga consumo de tokens em ai_usage_logs.

💡 Dica: a IA é configurada pra não inventar — se não encontra a info na conversa, deixa o campo vazio.

Configurar a ação

Ao adicionar a ação ai_extract_fields na automação:

Campos a extrair

Lista de campos que a IA deve procurar. Cada campo tem 3 propriedades:

• Chave (key): identificador interno (ex: email, cnpj).
• Instrução (instruction): prompt que orienta a IA o que procurar.
• Ex: "Extraia o email principal do cliente. Se ele mencionar mais de um, use o que parecer mais oficial.".
• Campo de destino (target): onde gravar o valor.

Campos de destino disponíveis

Lead nativo

• lead.name — Nome
• lead.email — Email
• lead.phone — Telefone
• lead.company — Empresa
• lead.instagram_username — @ Instagram
• lead.birthday — Aniversário (formato YYYY-MM-DD)
• lead.value — Valor potencial em R$
• lead.notes — Notas (concatenado, não sobrescreve)

Campos personalizados

• custom:42 — Campo personalizado #42 (substitua 42 pelo ID real do seu campo).
• Funciona com todos os tipos: text, number, currency, date, select, etc.
• Pra select: IA escolhe entre as opções disponíveis (não inventa).

Máximo de mensagens analisadas

Configure quantas mensagens recentes a IA deve analisar:

• Default: 50 mensagens.
• Mais mensagens = mais contexto, mas mais tokens.
• Menos mensagens = mais barato, mas IA pode perder info enterrada em conversas longas.

💡 Dica: 30-50 mensagens cobrem bem a maioria dos casos.

Exemplo prático

Cenário

Lead chega via WhatsApp e durante a conversa diz:

• "Oi, sou o João Silva da ACME Industries"
• "Meu email é [email protected]"
• "Preciso de orçamento pra 200 unidades, deve dar uns R$ 50.000"

Configuração da ação

Gatilho: message_received

Ação ai_extract_fields:
 Fields:
 - key: name
 instruction: "Extraia o nome completo do cliente."
 target: lead.name

 - key: email
 instruction: "Extraia o email principal do cliente."
 target: lead.email

 - key: company
 instruction: "Extraia o nome da empresa do cliente."
 target: lead.company

 - key: value
 instruction: "Extraia o valor potencial da venda em R$. Apenas o número."
 target: lead.value

 max_messages: 50

Resultado

Após algumas mensagens trocadas, IA lê o transcript e preenche:

• lead.name = "João Silva"
• lead.email = "[email protected]"
• lead.company = "ACME Industries"
• lead.value = 50000

Tudo automático. Vendedor pega lead já enriquecido.

Boas práticas pra prompts

Seja específico

❌ "Extraia o telefone" (genérico — IA pode pegar telefone de qualquer um mencionado). ✅ "Extraia o telefone principal de contato do cliente. Não use telefones de outras pessoas mencionadas."

Defina formato esperado

✅ "Extraia a data de aniversário no formato YYYY-MM-DD. Se não tiver ano, use 2000." ✅ "Extraia apenas o número, sem 'R$', vírgulas ou pontos. Ex: 5000 (não 'R$ 5.000,00')."

Lide com ambiguidade

✅ "Se cliente mencionar múltiplas empresas, use a mais recente." ✅ "Se valor for em outra moeda, deixe vazio."

Defina quando NÃO extrair

✅ "Se a empresa parecer fictícia ou genérica (ex: 'minha empresa'), deixe vazio."

Quando a IA NÃO sobrescreve

A IA é conservadora:

• ✅ Preenche só campos vazios (null ou '').
• ❌ Nunca sobrescreve dados existentes.

Exemplo:

• Lead já tem email = "[email protected]" (preenchido manualmente).
• IA detecta no chat "meu email é [email protected]".
• IA NÃO substitui — mantém [email protected].

💡 Dica: pra forçar atualização, limpe o campo manualmente antes da IA rodar (deixa null) ou edite o lead após.

Quanto tempo demora

A action é assíncrona (fila):

• Mensagem chega → automação dispara → job é enfileirado.
• Job é processado em 5-30 segundos (depende da fila + LLM).
• Resultado aparece na timeline do lead após processamento.

⚠️ Atenção: não é instantâneo — você não vê dados extraídos na hora. Aguarde alguns segundos e atualize a página do lead.

Custos (tokens)

Cada execução consome tokens:

• Mensagem média: ~50 tokens.
• 50 mensagens transcritas: ~3.000 tokens input.
• System prompt + schema: ~500 tokens.
• Resposta JSON: ~200 tokens.

Total típico: ~3.500-4.000 tokens por execução.

Se a quota mensal de tokens esgotou, a action não roda (skip silencioso) e registra evento ai_extract_skipped. Veja Quota de tokens.

Retentativas (retry)

Se a IA falha (timeout, rate limit OpenAI, JSON inválido):

• Tentativa 1: imediata.
• Tentativa 2: 30s depois.
• Tentativa 3: 120s depois.

Após 3 falhas, registra ai_extract_failed na timeline e desiste.

Gatilhos comuns pra usar

Gatilho message_received

Roda a cada mensagem — detecta dados conforme conversa avança.

⚠️ Atenção: muito frequente — pode consumir muitos tokens. Use condições:

• "Só quando há mais de 5 mensagens na conversa".
• "Só quando lead.email é vazio".

Gatilho conversation_created

Roda uma vez quando conversa é criada — mas a essa altura geralmente cliente só mandou 1 mensagem (pouco contexto).

Gatilho lead_stage_changed

Útil quando lead muda pra etapa que requer dados completos (ex: "Proposta") — IA preenche o que falta.

Verificar resultados

Cada execução cria evento na timeline do lead:

Abra o lead, aba Timeline ou Histórico, veja os eventos.

Limitações conhecidas

• Apenas em conversas WhatsApp (Instagram e site limitados).
• Não atualiza relacionamentos (ex: não cria tags via essa action — use add_tag_lead separado).
• Não dispara outras automações ao atualizar campos (sem cascata).
• Idioma da IA: configurada pra português, pode performar pior em outros idiomas dependendo do modelo.

Combinar com outras ações

Use a ação junto com outras pra fluxo completo:

Gatilho: message_received

Ações:
1. ai_extract_fields (extrai dados)
2. add_tag_lead "iniciado" (marca que foi processado)
3. send_whatsapp_message "Oi {{lead.name}}, recebemos sua mensagem..."

Após IA preencher lead.name, a mensagem subsequente já usa o nome correto.

Erros comuns

"Action não roda"

• Verifique se há tokens disponíveis (quota não esgotada).
• Verifique se a conversa tem mensagens (>= 1).
• Confira logs: ai_extract_skipped indica motivo.

"IA preencheu valor errado"

• Reformule a instruction com mais clareza.
• Restrinja com mais detalhes (formato, contexto).
• Considere usar notes como fallback (registra info sem sobrescrever campo crítico).

"Custo muito alto de tokens"

• Reduza max_messages (ex: de 50 pra 20).
• Adicione condições no gatilho pra rodar menos vezes.

Próximos passos

• Pra mandar mensagens com dados extraídos, veja Ações de mensagem.
• Pra entender quota de tokens, veja Quota de tokens.

Artigos relacionados

• Criar automação
• Quota de tokens
• Campos personalizados
• Ações de mensagem