Rastreamento de UTM em leads e conversas WhatsApp

Use este guia para definir como cada canal deve enviar a origem de campanha para a Agilize. A regra principal é simples: a conversa ou o lead precisa chegar com a informação de onde veio, qual campanha gerou o contato e quais identificadores de mídia devem ser preservados para análise posterior.

Esses dados ajudam a analisar campanhas no CRM, comparar qualidade comercial por origem e alimentar integrações de conversão offline quando o lead avança no funil.

Premissas gerais

• Defina uma convenção única de UTM entre mídia, landing pages, formulários e integrações. Isso evita que a mesma campanha apareça com nomes diferentes nos relatórios.
• A origem precisa chegar junto com a primeira conversa ou com o cadastro do lead. Se a informação não chega nesse momento, a correção depois tende a ser manual ou depender de integração específica.
• Em campanhas da Meta que abrem o WhatsApp diretamente, a atribuição depende dos dados que a própria Meta envia para a conversa.
• Em campanhas que passam por landing page antes do WhatsApp, a página precisa carregar UTMs no link do anúncio e usar o rastreador para levar essa origem até a Agilize.
• Quando um lead nasce a partir de uma conversa que já tem origem de campanha, a Agilize mantém essa origem no lead para análise no CRM, relatórios e conversões.

Cenário 1: campanha Meta com entrega direta no WhatsApp

Use este cenário quando o anúncio da Meta abre uma conversa diretamente no WhatsApp do número vinculado ao Business Manager.

Quando a conversa chega pela integração oficial, a Agilize usa os dados de referral enviados pela Meta para preencher automaticamente a sala. Se um lead for gerado a partir dessa conversa, a atribuição é propagada para o lead.

Pré-requisitos:

• número WhatsApp vinculado e operacional na Meta/Business Manager;
• número conectado como canal WhatsApp na Agilize;
• campanha configurada para destino direto no WhatsApp;
• webhook do canal recebendo a primeira mensagem da conversa.

Campos que podem ser preenchidos quando a Meta envia os dados:

Nesse cenário, não é necessário instalar o rastreador de landing page para a conversa direta do anúncio. O rastreador passa a ser necessário quando o clique vai primeiro para uma página externa.

Cenário 2: campanha entregue em landing page

Use este cenário quando o anúncio leva o visitante para uma LP, site, página de produto ou formulário antes do WhatsApp.

Nessa jornada, o WhatsApp não recebe automaticamente as UTMs da página. Para preservar a origem, instale o Whatsapp - Botão e Rastreador UTM na página. O rastreador captura UTMs e click IDs da URL, mantém o histórico de atribuição no site e permite que a primeira conversa no WhatsApp chegue na Agilize com origem de campanha.

Premissas importantes:

• a URL da LP precisa carregar os parâmetros de campanha, como utm_source, utm_medium, utm_campaign, utm_content, fbclid, gclid, gbraid, wbraid ou ttclid;
• o rastreador precisa estar carregado antes do clique no botão de WhatsApp;
• o usuário precisa enviar a mensagem pré-preenchida sem apagá-la;
• a Agilize lê a origem na primeira mensagem recebida da conversa;
• se o visitante já tinha histórico de atribuição no site, a estratégia configurada define se a conversa usará o primeiro ou o último contato;
• mensagens iniciais objetivas e UTMs padronizadas aumentam a previsibilidade do rastreamento.

Exemplo de URL de LP:

https://www.suaempresa.com.br/landing-page?utm_source=facebook&utm_medium=paid_social&utm_campaign=nome-da-campanha&utm_content=criativo-a

Na campanha, coloque as UTMs no link da landing page. O rastreador se encarrega de levar essa origem para o WhatsApp quando o visitante clicar no botão.

Cenário 3: leads por integração direta ou formulário próprio

Use este cenário quando o lead é criado por um formulário do seu site, checkout, aplicação própria ou integração direta com a Agilize.

Nesse caso, o sistema que cria o lead deve enviar os campos de UTM junto com o cadastro. O ideal é capturar esses valores na página, armazenar em campos ocultos do formulário e enviar os dados junto com a integração.

Campos recomendados em utm:

Campos recomendados em utmClick:

Exemplo de dados enviados:

{
  "name": "Maria Souza",
  "phones": [{ "phone": "+5511999999999" }],
  "emails": [{ "email": "maria@empresa.com.br" }],
  "utm": {
    "provider": "meta",
    "source": "facebook",
    "medium": "paid_social",
    "campaign": "lp-whatsapp-julho",
    "content": "criativo-video-1",
    "url": "https://www.suaempresa.com.br/lp?utm_source=facebook"
  },
  "utmClick": {
    "fbclid": "fbclid-do-clique"
  }
}

Para integrações via API, consulte também Introdução à API, Autenticação e o endpoint de criação de oportunidade.

Cenário 4: leads criados por webhook de entrada

Use este cenário quando um sistema externo envia eventos para a Agilize e um fluxo de webhook cria o lead.

Os dados recebidos podem ter formatos diferentes, mas os campos de origem precisam ser mapeados no node que gera a entidade. Para leads, o mapeamento aceita chaves como:

• utm.provider
• utm.source
• utm.medium
• utm.campaignId
• utm.campaign
• utm.groupId
• utm.group
• utm.creativeId
• utm.creative
• utm.content
• utm.term
• utm.url
• utm.ref
• utmClick.fbclid
• utmClick.ctwaClid
• utmClick.gclid
• utmClick.gbraid
• utmClick.wbraid
• utmClick.ttclid

Exemplo de mapeamento:

utm.provider      = meta
utm.source        = {{payload.tracking.utm_source}}
utm.medium        = {{payload.tracking.utm_medium}}
utm.campaignId    = {{payload.tracking.campaign_id}}
utm.creativeId    = {{payload.tracking.ad_id}}
utmClick.fbclid   = {{payload.tracking.fbclid}}

Quando o provedor envia utm_campaign como nome e não como ID, mapeie em utm.campaign. Quando envia um ID técnico, prefira utm.campaignId.

Cenário 5: leads por Facebook Forms

Use este cenário quando o lead vem de formulários instantâneos da Meta.

Na integração de Facebook Forms, a Agilize cria o lead a partir dos dados recebidos da Meta e preenche utm com o que a Meta entrega no evento ou na consulta do lead. Quando a Meta informa campanha, conjunto e anúncio, esses dados são salvos como utm.campaignId, utm.campaign, utm.groupId, utm.group, utm.creativeId e utm.creative.

Premissas:

• a Página precisa estar conectada para receber eventos de lead;
• o formulário precisa estar cadastrado quando a configuração exigir aceitar apenas formulários registrados;
• os campos de contato do formulário devem permitir identificar nome, telefone ou e-mail;
• a atribuição depende dos dados que a Meta disponibiliza para aquele lead.

Se a Meta enviar o lead como orgânico, a mídia pode ser registrada como organic. Se vier de anúncio, a mídia tende a ser paid.

Boas práticas de convenção

• Defina uma convenção única para utm_source, utm_medium, utm_campaign, utm_content e utm_term.
• Use IDs técnicos nos campos *Id e nomes legíveis nos campos sem Id.
• Não grave fbclid, gclid, gbraid, wbraid ou ttclid dentro de utm.campaign ou utm.content; use utmClick.
• Sempre preserve utm.url quando a origem veio de uma página, porque ela ajuda a auditar a jornada.
• Teste cada canal com um lead real de homologação antes de avaliar campanhas em relatório.
• Trate UTM como dado de atribuição comercial. Evite enviar informações pessoais ou dados sensíveis nesses campos.

Próximo passo

Para campanhas que passam por landing page ou site antes do WhatsApp, siga para Configuração do Whatsapp - Botão e Rastreador UTM.