# Agilize Docs para IA - Página atual Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize. Use esta versão quando a pergunta do usuário estiver restrita ao documento atual. Última geração: 2026-07-24T05:41:37.667Z ## Página - Título: Rastreamento de UTM em leads e conversas WhatsApp - URL humana: https://agilize.app/docs/configuracao/canais-whatsapp-integracoes/rastreamento-utm-leads-whatsapp - Leitura completa para IA: https://agilize.app/docs/llms.txt - Descrição: Entenda como a Agilize atribui campanhas por UTM em WhatsApp direto, landing pages, formulários próprios, webhooks de entrada e Facebook Forms. ## Seções - Premissas gerais - Cenário 1: campanha Meta com entrega direta no WhatsApp - Cenário 2: campanha entregue em landing page - Cenário 3: leads por integração direta ou formulário próprio - Cenário 4: leads criados por webhook de entrada - Cenário 5: leads por Facebook Forms - Boas práticas de convenção - Próximo passo ## Conteúdo da página # 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. --- title: "Como a atribuição chega na Agilize" caption: "Cada entrada tem uma forma correta de carregar UTM. Depois que a sala ou lead recebe a origem, o dado acompanha a operação." definition: | flowchart LR A[Anúncio Meta direto para WhatsApp] --> B[Sala com referral Meta] C[Anúncio para LP] --> D[Rastreador preserva UTM no WhatsApp] E[Formulário próprio] --> F[Lead criado com origem de campanha] G[Webhook de entrada] --> H[Mapeamento de campos UTM] I[Facebook Forms] --> J[UTM enviada pela Meta] B --> K[Lead gerado pela conversa] D --> B F --> L[CRM e conversões] H --> L J --> L K --> L --- ## 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: | Campo | Uso | | --- | --- | | `utm.provider` | Normalmente `meta`. | | `utm.source` | Canal de origem, como `whatsapp`, `facebook` ou `instagram`, conforme o dado recebido. | | `utm.medium` | Categoria do tráfego, normalmente mídia paga quando o clique veio de anúncio. | | `utm.campaignId` e `utm.campaign` | ID e nome da campanha, quando disponíveis. | | `utm.groupId` e `utm.group` | ID e nome do conjunto de anúncios ou grupo equivalente. | | `utm.creativeId` e `utm.creative` | ID e nome do anúncio ou criativo. | | `utmClick.ctwaClid` | Click ID de campanhas Click-to-WhatsApp. | | `utmClick.fbclid` | Click ID web da Meta quando enviado ou presente na URL de origem. | 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](/docs/configuracao/canais-whatsapp-integracoes/configuracao-whatsapp-botao-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: ```text 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`: | Campo | O que enviar | | --- | --- | | `utm.provider` | Provedor normalizado, como `meta`, `google`, `linkedin`, `tiktok` ou `microsoft`. | | `utm.source` | Origem específica, como `facebook`, `instagram`, `search`, `youtube`, `email` ou `referral`. | | `utm.medium` | Mídia/categoria, como `paid`, `paid_social`, `cpc`, `organic`, `email` ou `referral`. | | `utm.campaignId` | ID da campanha na plataforma de mídia, quando existir. | | `utm.campaign` | Nome da campanha ou valor de `utm_campaign`. | | `utm.groupId` | ID do conjunto de anúncios, grupo de anúncios ou equivalente. | | `utm.group` | Nome do grupo/conjunto de anúncios. | | `utm.creativeId` | ID do anúncio, criativo ou peça. | | `utm.creative` | Nome do anúncio, criativo ou peça. | | `utm.content` | Valor de `utm_content`. | | `utm.term` | Valor de `utm_term`. | | `utm.url` | URL da página onde o lead foi capturado. | | `utm.ref` | Referência adicional recebida do canal, quando existir. | Campos recomendados em `utmClick`: | Campo | O que enviar | | --- | --- | | `utmClick.fbclid` | Facebook Click ID. | | `utmClick.ctwaClid` | Click-to-WhatsApp Click ID da Meta. | | `utmClick.gclid` | Google Click ID. | | `utmClick.gbraid` | Google braid para alguns cenários iOS/app. | | `utmClick.wbraid` | Google braid para alguns cenários iOS/web. | | `utmClick.ttclid` | TikTok Click ID. | Exemplo de dados enviados: ```json { "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](/docs/desenvolvedores/guias-integracao/introducao), [Autenticação](/docs/desenvolvedores/guias-integracao/autenticacao) e o endpoint de [criação de oportunidade](/docs/desenvolvedores/referencia-tecnica/api/crm-lead/oportunidade/post-crm-lead-lead). ## 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: ```text 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](/docs/configuracao/canais-whatsapp-integracoes/configuracao-whatsapp-botao-rastreador-utm).