WhatsApp Attribution Bridge 0.3.4

Plugin beta para ligar a origem de um clique no WordPress ao contato criado quando a mensagem chega pelo WhatsApp no GoHighLevel.

Escopo deste MVP

• Captura first-touch e last-touch no localStorage, com validade configurável.
• Captura os parâmetros do Campaign URL Builder do Google (utm_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content), IDs de campanha, gclid, gbraid, wbraid, fbclid, msclkid e referrer.
• Cria mensagens rastreáveis no painel do WordPress.
• Injeta duas cópias invisíveis de um token aleatório na mensagem.
• Carrega o tracker no <head> para preparar os links antes de o visitante conseguir clicar.
• Registra o clique com sendBeacon() sem bloquear a abertura do WhatsApp.
• Preserva first-touch já preenchido no contato e atualiza last-touch.
• Atualiza o contato usando a API de Contatos v3 e adiciona uma tag após a atribuição.
• Repete automaticamente integrações pendentes após falhas transitórias do HighLevel.
• Aba "Registros" no painel mostra os últimos 100 cliques/atribuições direto da tabela, com filtro por status, seleção múltipla com "selecionar todos", limpeza por status e detalhe dos UTMs/click IDs capturados em cada clique.
• Aba "Webhooks" registra somente o diagnóstico derivado das chamadas recebidas em /wab/v1/match, sem persistir corpo bruto, IP ou dados do paciente. Permite colar um payload para teste sem armazená-lo.
• Painel de diagnóstico com checagens de configuração e botão "Testar conexão com o HighLevel".
• Falha de forma aberta: sem JavaScript, o link continua abrindo o WhatsApp com a mensagem visível.
• Não solicita diretamente nome, telefone ou conteúdo da conversa. URLs são gravadas sem query string ou fragmento; UTMs e IDs permitidos ficam em campos separados. As landing pages não devem colocar dados pessoais no caminho da URL.

O MVP não faz casamento temporal. Mensagens cujo token seja apagado entram normalmente no HighLevel, mas ficam sem atribuição automática. Inferência temporal só deve ser adicionada depois de medir a perda real, em campos separados dos dados exatos.

Requisitos

• WordPress 6.0 ou superior.
• PHP 7.4 ou superior.
• HTTPS.
• WhatsApp conectado ao mesmo número usado nas mensagens do plugin.
• Subconta HighLevel com permissão para criar workflows e Private Integrations.
• Private Integration Token com contacts.readonly e contacts.write.

Instalação

1. Compacte a pasta whatsapp-attribution-bridge em ZIP.
2. No WordPress, acesse Plugins → Adicionar plugin → Enviar plugin.
3. Instale e ative.
4. Abra WhatsApp Attribution.
5. Informe o Location ID, token, segredo do webhook, retenção e mapa de campos.
6. Cadastre uma mensagem rastreável com o número exatamente igual ao conectado ao HighLevel.
7. Ative o rastreamento somente depois de concluir os testes de homologação.

Para evitar que o Private Integration Token apareça em backups do banco, adicione ao wp-config.php:

define('WAB_HL_TOKEN', 'pit-SEU-TOKEN');

O campo do painel existe apenas como fallback para o beta.

Uso nos botões

A tela de mensagens fornece um link seguro parecido com:

https://wa.me/5571999999999?text=Ol%C3%A1...#wab=agendamento-geral

Esse link pode ser colado no Elementor. Se o plugin estiver desligado ou o JavaScript falhar, ele continua sendo um link normal do WhatsApp.

Em conteúdo WordPress também é possível usar:

[wab_whatsapp message="agendamento-geral" label="Agendar pelo WhatsApp" class="meu-botao"]

Workflow no HighLevel

Gatilho:

Customer Replied
Reply Channel = WhatsApp
Contato não possui a tag wab-attribution-processed

O plugin aceita tanto o payload de evento do HighLevel (contactId, locationId, body) quanto os formatos do workflow (contact_id, location.id, message.body). Se "Dados personalizados" existirem, eles têm prioridade.

Adicione um webhook POST para a URL mostrada no painel do plugin. Se a mensagem chegar antes do registro do clique, o plugin guarda a associação por dez minutos e conclui a atribuição assim que o clique aparece. Repetir o webhook continua sendo seguro e idempotente.

Header:

Authorization: Bearer SEU_SEGREDO
Content-Type: application/json

Body:

{
  "contact_id": "{{contact.id}}",
  "location_id": "{{location.id}}",
  "message": "{{message.body}}"
}

O plugin adiciona a tag wab-attribution-processed somente depois que o contato é atualizado. A repetição do mesmo webhook é idempotente.

Mapa de campos

Crie campos de texto no contato do HighLevel e associe seus IDs às chaves abaixo:

{
  "first_source": "ID_DO_CAMPO",
  "first_campaign": "ID_DO_CAMPO",
  "first_term": "ID_DO_CAMPO",
  "first_click_id": "ID_DO_CAMPO",
  "first_ad_group": "ID_DO_CAMPO",
  "first_landing": "ID_DO_CAMPO",
  "last_source": "ID_DO_CAMPO",
  "last_campaign": "ID_DO_CAMPO",
  "last_term": "ID_DO_CAMPO",
  "last_click_id": "ID_DO_CAMPO",
  "last_ad_group": "ID_DO_CAMPO",
  "last_landing": "ID_DO_CAMPO",
  "confidence": "ID_DO_CAMPO",
  "method": "ID_DO_CAMPO",
  "message_id": "ID_DO_CAMPO"
}

Também são aceitas as chaves opcionais first_medium, first_content, last_medium e last_content.

Testes locais

JavaScript, sem dependências:

node .\tests\tracker.test.js

PHP, quando o executável estiver disponível:

php .\tests\core-test.php

Antes de publicar uma versão, valide também a sintaxe dos arquivos:

php -l .\whatsapp-attribution-bridge.php

Antes de produção, valide os caracteres invisíveis em Android, iOS e WhatsApp Web e confirme se {{message.body}} os preserva no webhook. Se o merge field remover os caracteres, o próximo passo é consultar a mensagem original pela Conversations API, não trocar o alfabeto às cegas.

Atualizações

O plugin se autoatualiza via GitHub, usando a lib Plugin Update Checker (includes/plugin-update-checker/). O WordPress passa a mostrar o aviso normal de atualização na tela de Plugins e atualiza com um clique, sem precisar do WordPress.org.

Para publicar uma nova versão:

1. Suba a alteração pra main no repositório https://github.com/azelfo/whatsapp-attribution-bridge.
2. Atualize o número de versão no cabeçalho de whatsapp-attribution-bridge.php (Version: e a constante WAB_VERSION) e neste README.
3. Crie uma tag git tag vX.Y.Z && git push --tags (ou uma Release pelo site do GitHub).

Dentro de algumas horas (ou na próxima vez que alguém abrir a tela de Plugins) o WordPress detecta a tag nova e oferece a atualização.

Segurança e desempenho

• O endpoint público aceita no máximo 30 registros por minuto por IP, em janela fixa, e payloads de até 8 KB. Por padrão usa o IP visto pelo servidor.
• O webhook exige segredo comparado com hash_equals().
• O token do HighLevel nunca é enviado ao navegador.
• A tabela armazena somente atribuição, token e ID técnico do contato.
• Registros expiram pela rotina diária de retenção.
• Atribuições antigas no navegador expiram no prazo configurado, por padrão 90 dias.
• Falhas do HighLevel mantêm o contato vinculado e são tentadas novamente a cada 5 minutos, até 8 tentativas; os últimos erros aparecem no painel.
• Não há chamadas ao HighLevel durante o carregamento da página.
• O plugin só altera links com #wab= ou data-wab-message.
• Ao desinstalar, os dados são preservados por padrão. A exclusão total precisa ser ativada explicitamente no painel antes da remoção.

Se a origem estiver protegida pela Cloudflare e não aceitar acesso direto, habilite o IP real no wp-config.php:

define('WAB_TRUST_CLOUDFLARE', true);

Checklist de homologação

1. Confirmar que o número wa.me é o número conectado ao HighLevel.
2. Confirmar recebimento de uma mensagem comum no HighLevel.
3. Confirmar contact.id, location.id e message.body no webhook.
4. Testar uma atualização GET + PUT em contato de teste.
5. Testar URL com UTMs e GCLID.
6. Testar segunda chamada idêntica do webhook.
7. Testar contato que já possui first-touch.
8. Testar com cache, Cloudflare e plugin de segurança ativos.
9. Testar com JavaScript desabilitado: o WhatsApp deve continuar abrindo.
10. Ativar primeiro em uma única landing page.