# Atribuição de anúncios "Clique para o WhatsApp" Se você executa anúncios "Clique para o WhatsApp" da Meta (Facebook/Instagram), o Your AI Connector pode informar de qual anúncio cada lead do WhatsApp veio — e fornecer o identificador de clique da Meta necessário para reportar conversões reais de volta à Meta. Isso permite que suas campanhas de anúncios sejam otimizadas para vendas e agendamentos reais, não apenas para "pessoas que iniciaram uma conversa." --- ## O que é capturado Quando alguém toca em um anúncio "Clique para o WhatsApp" e envia uma mensagem para sua empresa, a Meta anexa informações ocultas de referência à primeira mensagem. O Your AI Connector as lê automaticamente e as armazena no contato. Sem configuração, sem ajustes — simplesmente acontece. As informações capturadas são armazenadas no contato como `ad_referral` e contêm: | Campo | O que é | |---|---| | `ctwa_clid` | O identificador de clique da Meta. Este é o valor que você envia para a API de Conversões da Meta para atribuir uma conversão posterior ao clique exato no anúncio. Fica vazio para referências de postagens orgânicas (veja abaixo). | | `source_id` | O ID do anúncio (ou postagem) em que a pessoa clicou. | | `source_type` | Pode ser `ad` (um anúncio pago "Clique para o WhatsApp") ou `post` (uma postagem orgânica no Facebook/Instagram). | | `source_url` | O link associado ao conteúdo do anúncio. | | `headline` | O texto do título do anúncio. | | `body` | O texto do corpo do anúncio. | | `channel` | O canal pelo qual a referência chegou (atualmente sempre `whatsapp`). | | `captured_at` | Quando a referência foi registrada pela primeira vez no contato. | Você pode ver isso no [painel de visualização rápida](../get-started/creating-contacts.md) de um contato se tiver configurado um campo personalizado para ele, ou lê-lo diretamente por meio de webhooks e da API (veja abaixo) — ele não é exibido como seu próprio campo rotulado na tabela de Contatos. > **Uma coisa que o payload não informa:** em qual dos seus números a conversa chegou. Não há um id de página ou id de Conta do WhatsApp Business nele. Com um único número, isso não importa; se você utiliza vários números em diferentes Páginas do Facebook, precisará mapear isso do seu lado. --- ## Em qual conexão isso funciona > Isso funciona **apenas na conexão oficial da API do WhatsApp.** A Meta entrega as informações estruturadas de referência (incluindo `ctwa_clid`) apenas através da API oficial do WhatsApp Business. A **conexão não oficial do WhatsApp (web) não recebe isso** — não há dados de clique de anúncio disponíveis nessa conexão, devido ao design de como ela funciona. Portanto, se a atribuição de anúncios de ciclo fechado é importante para você, execute suas campanhas "Clique para o WhatsApp" usando um número conectado via API oficial do WhatsApp. --- ## Comportamento de primeiro toque A referência é capturada na **primeira** mensagem que um contato envia a partir de um anúncio. Se o mesmo contato clicar posteriormente em um anúncio diferente e esse novo clique contiver um identificador de clique, o `ad_referral` armazenado é atualizado para que o ID do clique permaneça atualizado para fins de relatório. Referências de postagens orgânicas (que não possuem `ctwa_clid`) nunca sobrescrevem um ID de clique de anúncio pago capturado anteriormente. --- ## Enviando os dados para a Meta ou Google Ads O Your AI Connector captura os dados de atribuição e os expõe, mas **não** envia conversões para a Meta ou Google nativamente para você hoje. Você encaminha os dados usando webhooks e uma ferramenta de automação. O objeto `ad_referral` está incluído na seção `contact` dos eventos de [webhook](webhooks.md) de saída (por exemplo, Nova Mensagem, Contato Retomado, Tags de Contato Atualizadas e eventos de análise, como Agendamento Confirmado). Uma configuração típica de ciclo fechado: 1. Um lead clica no seu anúncio "Clique para o WhatsApp" e envia uma mensagem. O Your AI Connector registra o `ad_referral` (incluindo o `ctwa_clid`) no contato. 2. À medida que o lead avança — agendou uma chamada, tornou-se cliente, foi perdido — você marca esse resultado (veja "Carregando a etapa do funil" abaixo). 3. Um webhook é disparado para sua ferramenta de automação (Zapier, Make ou Pabbly) contendo tanto o resultado quanto o `ctwa_clid` do contato. 4. Sua ferramenta de automação chama a API de Conversões da Meta (usando o `action_source = business_messaging` e o `ctwa_clid`) ou o Google Ads (Importação de Conversões Offline / Conversões Aprimoradas para Leads) para reportar a conversão. Dessa forma, a Meta e o Google aprendem quais anúncios produziram resultados reais e otimizam com base neles. --- ## Levando o estágio do funil Para relatar uma conversão, você geralmente precisa de duas coisas: o ID do clique (capturado automaticamente) e o resultado (que você define). A maneira mais confiável de anexar um resultado é com **tags**, porque a aplicação de uma tag dispara o webhook `contact_tags_updated` — e esse payload inclui o `ad_referral` do contato. (Remover uma tag não o dispara; veja [Tags de Contato Atualizadas](webhooks.md#contact-tags-updated-webhook).) Você pode aplicar tags automaticamente: - Deixe seu Agente de IA marcar o contato durante a conversa — configure regras de marcação automática na configuração do agente. É assim que o padrão "uma página de destino por anúncio → uma mensagem de entrada → uma tag" funciona se você quiser rotular a origem por conta própria. - Ou marque manualmente a partir de Chats ou da página de Contatos. Sempre que uma tag relevante é alterada, o webhook é disparado com o ID do clique anexado, pronto para ser encaminhado como uma conversão. A URL do webhook é definida na própria tag, na aba **Tags** do agente (ou campanha) ao qual o contato pertence — não nas Configurações. Cada tag recebe sua própria URL, e todas podem apontar para o mesmo endpoint se você quiser um único local para receber tudo. ### Lendo um click id que você já perdeu `ad_referral` também é retornado pela API tanto em `GET /v1/contacts/{id}` (como `adReferral`) quanto no endpoint de lista de contatos (como `ad_referral`), portanto, se o seu receptor estava fora do ar ou se você está conciliando dados posteriormente, você pode ler o click id de volta em vez de esperar pelo próximo webhook. Contatos que chegaram antes de o click id ser registrado neles possuem `null` aqui — o valor só pode ser capturado a partir da própria mensagem recebida, então não há nada a ser preenchido retroativamente. --- ## Limitações - Apenas conexão oficial da API do WhatsApp (não a conexão web não oficial). - Ainda não há integração nativa de um clique com a Meta CAPI ou Google Ads — você encaminha os dados via Zapier/Make/Pabbly. Se você deseja uma integração nativa, informe o suporte em hi@youraiconnector.com. - A atribuição é capturada daqui para frente, a partir do momento em que isso estiver ativo. Ela não pode ser preenchida retroativamente em conversas que ocorreram antes. --- ## Próximos passos - [Webhooks](webhooks.md) — veja o payload completo e quais eventos incluem `ad_referral`. - [Usando Tags para Rotular Contatos](../get-started/creating-tags.md) — configure as tags que carregam seus estágios de funil.