# Atribuição de anúncios "Click-to-WhatsApp" Se publica anúncios "Click to WhatsApp" na Meta (Facebook/Instagram), o Your AI Connector pode dizer-lhe de que anúncio veio cada lead do WhatsApp — e fornecer-lhe o identificador de clique da Meta de que necessita para comunicar conversões reais à Meta. Isto permite que as suas campanhas publicitárias sejam otimizadas para vendas e reservas reais, e não apenas para "pessoas que iniciaram uma conversa". --- ## O que é capturado Quando alguém toca num anúncio "Click-to-WhatsApp" e envia uma mensagem à sua empresa, a Meta anexa informações de referência ocultas a essa primeira mensagem. O Your AI Connector lê-as automaticamente e guarda-as no contacto. Sem configuração, sem definições — acontece simplesmente. As informações capturadas são armazenadas no contacto como `ad_referral` e contêm: | Campo | O que é | |---|---| | `ctwa_clid` | O identificador de clique da Meta. Este é o valor que envia para a API de Conversões da Meta para atribuir uma conversão a jusante ao clique exato no anúncio. Fica vazio para referências de publicações orgânicas (ver abaixo). | | `source_id` | O ID do anúncio (ou publicação) em que a pessoa clicou. | | `source_type` | Ou `ad` (um anúncio pago "Click-to-WhatsApp") ou `post` (uma publicação orgânica do Facebook/Instagram). | | `source_url` | A ligação associada 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 através do qual a referência chegou (atualmente sempre `whatsapp`). | | `captured_at` | Quando a referência foi registada pela primeira vez no contacto. | Pode ver isto no [painel de visualização rápida](../get-started/creating-contacts.md) de um contacto se tiver configurado um campo personalizado para o efeito, ou lê-lo diretamente através de webhooks e da API (ver abaixo) — não aparece como um campo próprio com etiqueta na tabela de Contactos. > **Uma coisa que o payload não lhe diz:** em qual dos seus números a conversa foi recebida. Não existe nenhum ID de página ou ID de Conta WhatsApp Business nele. Com um único número, isso não importa; se utilizar vários números em diferentes Páginas do Facebook, terá de mapear isso do seu lado. --- ## Em que ligação funciona > Isto funciona **apenas na ligação oficial da API do WhatsApp.** A Meta apenas fornece as informações de referência estruturadas (incluindo `ctwa_clid`) através da API oficial do WhatsApp Business. A **ligação não oficial do WhatsApp (web) não as recebe** — não existem dados de cliques em anúncios disponíveis nessa ligação, devido à forma como esta funciona. Portanto, se a atribuição de anúncios de ciclo fechado é importante para si, execute as suas campanhas "Click-to-WhatsApp" através de um número ligado via API oficial do WhatsApp. --- ## Comportamento de primeiro contacto A referência é capturada na **primeira** mensagem que um contacto envia a partir de um anúncio. Se o mesmo contacto clicar posteriormente num anúncio diferente e esse novo clique contiver um identificador de clique, o `ad_referral` armazenado é atualizado para que o ID de clique se mantenha atualizado para efeitos de relatório. As referências de publicações orgânicas (que não têm `ctwa_clid`) nunca substituem um ID de clique de anúncio pago capturado anteriormente. --- ## Obter os dados para a Meta ou Google Ads O Your AI Connector captura os dados de atribuição e expõe-nos, mas **não** envia conversões para a Meta ou Google de forma nativa atualmente. Deve encaminhar os dados utilizando webhooks e uma ferramenta de automatização. O objeto `ad_referral` está incluído na secção `contact` dos eventos de [webhook](webhooks.md) de saída (por exemplo, Nova Mensagem, Contacto Retomado, Etiquetas de Contacto Atualizadas e eventos de análise como Marcação de Reunião). Uma configuração típica de ciclo fechado: 1. Um lead clica no seu anúncio "Click-to-WhatsApp" e envia-lhe uma mensagem. O Your AI Connector regista o `ad_referral` (incluindo o `ctwa_clid`) no contacto. 2. À medida que o lead progride — marcou uma chamada, tornou-se cliente, foi perdido — marca esse resultado (consulte "Carrying the funnel stage" abaixo). 3. Um webhook é disparado para a sua ferramenta de automatização (Zapier, Make ou Pabbly) transportando tanto o resultado como o `ctwa_clid` do contacto. 4. A sua ferramenta de automatização chama a Conversions API da Meta (utilizando o `action_source = business_messaging` e o `ctwa_clid`) ou o Google Ads (Importação de Conversões Offline / Conversões Avançadas para Leads) para comunicar a conversão. Desta forma, a Meta e o Google aprendem quais os anúncios que produziram resultados reais e otimizam com base neles. --- ## Transportar a fase do funil Para comunicar uma conversão, normalmente precisa de duas coisas: o ID do clique (capturado automaticamente) e o resultado (que define). A forma mais fiável de associar um resultado é através de **etiquetas**, porque a aplicação de uma etiqueta dispara o webhook `contact_tags_updated` — e esse payload inclui o `ad_referral` do contacto. (Remover uma etiqueta não o dispara; consulte [Contact Tags Updated](webhooks.md#contact-tags-updated-webhook).) Pode aplicar etiquetas automaticamente: - Deixe o seu Agente de IA etiquetar o contacto durante a conversa — configure regras de etiquetagem automática na configuração do agente. É assim que funciona o padrão "uma página de destino por anúncio → uma mensagem de entrada → uma etiqueta", caso pretenda identificar a origem manualmente. - Ou etiquete manualmente a partir das Conversas ou da página de Contactos. Sempre que uma etiqueta relevante é alterada, o webhook é disparado com o ID do clique anexado, pronto a ser reencaminhado como uma conversão. O URL do webhook é definido na própria etiqueta, no separador **Etiquetas** do agente (ou campanha) a que o contacto pertence — não nas Definições. Cada etiqueta obtém o seu próprio URL e todos podem apontar para o mesmo endpoint, se pretender um único local para receber tudo. ### Ler um ID de clique que já perdeu `ad_referral` é também devolvido pela API tanto em `GET /v1/contacts/{id}` (como `adReferral`) como no endpoint da lista de contactos (como `ad_referral`), por isso, se o seu recetor estiver em baixo, ou se estiver a reconciliar dados a posteriori, pode ler o ID de clique em vez de esperar pelo próximo webhook. Os contactos que chegaram antes de o ID de clique ter sido registado neles têm `null` aqui — o valor só pode ser capturado a partir da própria mensagem recebida, pelo que não há nada para preencher retroativamente. --- ## Limitações - Apenas ligação oficial à API do WhatsApp (não a ligação web não oficial). - Ainda não existe integração nativa de um clique com a Meta CAPI ou Google Ads — encaminha os dados através do Zapier/Make/Pabbly. Se desejar uma integração nativa, informe o suporte em hi@youraiconnector.com. - A atribuição é capturada a partir do momento em que isto fica ativo. Não pode ser aplicada retroativamente a conversas que ocorreram anteriormente. --- ## Próximos Passos - [Webhooks](webhooks.md) — veja o payload completo e que eventos incluem `ad_referral`. - [Utilizar etiquetas para identificar contactos](../get-started/creating-tags.md) — configure as etiquetas que transportam as suas fases do funil.