Da origem da conversa às conversões.

Quero rastrear anúncios que abrem o WhatsApp e registrar a origem no Chatwoot. Antes de me orientar, pergunte se o número é novo, se já usa Cloud API ou se preciso manter o aplicativo WhatsApp Business; pergunte se uso Chatwoot Cloud ou instalação própria e quais acessos administrativos tenho.

Com base nisso, monte um checklist para a conexão oficial: aplicativo e portfólio Meta, número e WABA, token de servidor, caixa de entrada WhatsApp no Chatwoot, callback e inscrição messages. Diferencie verificação por SMS de registro na Cloud API e não mande apagar uma conta nem repetir o registro de um número já conectado. Se houver coexistência, confira elegibilidade e caminho específico na documentação atual.

Use os links oficiais deste guia e adapte os nomes de menus à minha versão. Nunca peça tokens, PIN, código SMS ou credenciais nesta conversa. Termine com um teste de entrada e resposta pelo Chatwoot e uma lista dos identificadores/configurações que preciso guardar no ambiente, sem revelar seus valores aqui.

A conexão oficial com o Chatwoot já funciona. Guie-me para obter uma amostra real do evento de mensagem message_created do Chatwoot, vindo de um anúncio direto para WhatsApp. Antes, pergunte se uso Cloud ou instalação própria, se tenho acesso autorizado à API, ao servidor ou a um receptor de webhooks controlado pela minha equipe. Não presuma que existe um botão de exportar webhook. A amostra desejada é do Chatwoot, não o payload bruto recebido da Meta.

Oriente um teste autorizado: clicar em um anúncio real, apagar a mensagem pronta antes de enviar e mandar “oi”. Identifique a conversa de teste. Se houver acesso à API, ensine a consultar suas mensagens com a credencial somente no meu ambiente para localizar referral; a resposta dessa consulta não é, por si, um webhook. Para capturar o evento message_created, ensine a usar registros autorizados do receptor existente ou configurar um receptor HTTPS controlado, validando a assinatura. Diferencie os formatos e não invente um envelope como se tivesse sido capturado. Confira o contrato e a versão do Chatwoot. Não use coletores públicos nem altere o callback Meta → Chatwoot. Sem acesso suficiente, indique exatamente o que solicitar ao administrador.

Antes de compartilhar qualquer amostra com você, forneça instruções ou um script local para remover nome, telefone, e-mail, endereço, texto pessoal, URLs de anexos, cookies, tokens e assinaturas. Troque IDs de conta, caixa, conversa, mensagem, anúncio e clique por valores fictícios consistentes, preservando chaves, tipos e relações; limite a amostra ao necessário. O original permanece protegido no meu ambiente. Mostre como revisar o resultado antes de colar aqui.

Na cópia anonimizada, localize content_attributes.referral.source_id (anúncio) e content_attributes.referral.ctwa_clid (clique). Não confunda source_id externo com o anúncio. Se referral ou clique estiverem ausentes, registre a ausência sem inventar valor. Entregue a amostra anonimizada e um mapa campo → função para usarmos no próximo prompt.

Use a amostra anonimizada e a configuração definidas antes para construir a integração completa. Entregue arquivos, dependências, migrações, .env.example sem segredos, testes locais e README. Use runtime com suporte ativo, armazenamento durável, POST /webhooks/chatwoot e GET /health.

No recebimento, valide X-Chatwoot-Signature com HMAC-SHA256 sobre timestamp + ponto + corpo bruto; confira X-Chatwoot-Timestamp antes de interpretar JSON. O extrator de origem só processa message_created, incoming, não privado, da conta e caixa configuradas. Leia content_attributes.referral com source_type=ad; preserve source_id como texto e ctwa_clid quando existir. Essa filtragem vale para origem: outros eventos de negócio terão tratamento próprio no passo 4. Não invente origem nem apague a anterior quando uma mensagem vier sem referral.

Guarde conta, caixa, conversa, mensagem, anúncio, clique e instante. Use unicidade por conta+mensagem, histórico e tarefa durável de sincronização. Confirme recebimento após persistir. Preserve os códigos reais no servidor; nunca use os valores fictícios da amostra em produção.

Consulte GET https://graph.facebook.com/{META_GRAPH_VERSION}/{AD_ID_SALVO} com Authorization: Bearer {META_MARKETING_TOKEN} e fields=id,account_id,name,adset{id,name},campaign{id,name},creative{id,name}. O token precisa de ads_read e acesso à conta. Valide o ID retornado e account_id autorizado. Guarde também IDs dos objetos relacionados, nomes e data da consulta. Antes de atualizar, confirme que a ocorrência ainda é a origem mais recente; resposta atrasada não sobrescreve clique posterior.

Leia GET /api/v1/accounts/{account_id}/conversations/{conversation_id} e grave POST no mesmo caminho com /custom_attributes, usando api_access_token. Preserve campos existentes, use merge:true quando suportado e serialize tarefas da conversa. Preencha os oito atributos rastreio listados no guia. Sinalize “Consulta pendente” quando a consulta falhar e “Nome indisponível” para nome ausente; preserve IDs, histórico e tentativa posterior controlada.

Configurações de servidor: CHATWOOT_URL, CHATWOOT_ACCOUNT_ID, CHATWOOT_INBOX_ID, CHATWOOT_API_TOKEN, CHATWOOT_WEBHOOK_SECRET, DATABASE_URL, META_GRAPH_VERSION, META_AD_ACCOUNT_ID e META_MARKETING_TOKEN. Nada de segredos no navegador ou nos logs. Teste origem válida/ausente, IDs sem perda de dígitos, conta/caixa erradas, assinatura inválida, duplicata, novo clique, acesso negado e respostas fora de ordem.

Continue o projeto e crie regras de conversão configuráveis. Use este caso como exemplo, não como regra universal: na loja do vestido, o contato é qualificado quando expressa intenção de reservar e o tamanho solicitado está disponível. Venda exige pedido e pagamento confirmados. “Vou comprar” não basta.

Pergunte quais critérios valem no meu negócio e qual fonte confiável comprova estoque, pedido e pagamento. Pode ser um sistema integrado ou confirmação registrada por um atendente autorizado; não presuma que uma frase do cliente ou um comprovante em imagem prova pagamento. Explique como ligar cada registro à oportunidade e à conversa corretas.

Use a IA para extrair intenção e evidências do contexto, confrontando-as com os dados verificados. Sem evidência suficiente ou diante de conflito, mantenha pendente para revisão. Trate eventos comerciais separadamente do extrator de referral; eles não precisam repetir o código do anúncio.

Persista o marco, a versão da regra, as evidências mínimas, a origem do dado e a data real. Congele a origem aplicável ao marco, incluindo ctwa_clid e IDs disponíveis; novos cliques não alteram o passado. Use chave única por oportunidade+marco e por pedido para compra. Primeiro produza os registros internos; ainda não envie à Meta.

Entregue o módulo e testes: intenção de reservar+tamanho disponível; tamanho indisponível; intenção sem confirmação; pedido sem pagamento; pedido e pagamento confirmados; evidência conflitante; mesmo marco repetido. Mostre a tabela esperado → obtido e peça minha validação das regras antes de ativá-las.

Acrescente ao projeto o envio à Meta dos marcos confirmados no passo anterior. Use Conversions API for Business Messaging para conversões ocorridas no WhatsApp: POST https://graph.facebook.com/{META_GRAPH_VERSION}/{META_DATASET_ID}/events. Event_name: QualifiedLead para o marco qualificado; Purchase para compra confirmada; LeadSubmitted somente se houver um marco de lead recebido explicitamente definido. Não use Lead genérico nem dispare todos na primeira mensagem.

Em cada evento use event_time real em segundos, action_source=business_messaging, messaging_channel=whatsapp e user_data com whatsapp_business_account_id e ctwa_clid preservado, sem hash neste clique. Ad_id fica no histórico interno e não substitui ctwa_clid. Sem clique válido, não invente vínculo. Purchase inclui custom_data.value e currency reais. Compra concluída no checkout do site usa o canal/contrato de website, mesmo se houve conversa antes.

Adicione META_DATASET_ID, META_CAPI_TOKEN e WHATSAPP_BUSINESS_ACCOUNT_ID ao ambiente. Confirme o dataset vinculado à WABA via GET /{WABA_ID}/dataset e explique POST quando necessário. Confira whatsapp_business_management, whatsapp_business_manage_events e acesso aos ativos. Credencial fica no servidor, com dados e logs limitados ao necessário.

Use registro durável e fila com reserva atômica por marco real. Estados: pendente, em envio, aceito, falha confirmada e resultado desconhecido. A Meta não deduplica esta rota: event_id não resolve repetição. Após timeout, queda do processo ou perda da resposta depois de possível envio, exija reconciliação antes de repetir; nunca reenvie cegamente. Em falha confirmada, respeite o erro documentado e a idade do evento, sem alterar sua data para fazê-lo passar.

Entregue arquivos, migrações e testes locais: compra com moeda/valor; marco repetido; duas tarefas concorrentes; token recusado; clique ausente; novo clique posterior; conversão de website; falha confirmada; timeout após possível aceite. Separe recibo da API, atribuição ao anúncio e elegibilidade de otimização. Não prometa melhora automática de campanha.

Revise o projeto completo e pergunte onde vou hospedar a integração e o banco. A partir do ambiente disponível, entregue arquivos finais, dependências, migrações, variáveis sem segredos, comandos de instalação, inicialização e atualização, além de instruções para HTTPS, persistência e execução da fila. Uma página estática ou esta conversa aberta não mantém o serviço rodando.

Forneça o endereço exato do meu serviço a cadastrar em Chatwoot → Settings → Integrations → Webhooks, os eventos necessários para origem e critérios e onde guardar o segredo de assinatura. Não confunda esse endereço com o callback Meta → Chatwoot. Explique como verificar /health, registros de erro e tarefas pendentes.

Monte e execute primeiro testes locais sem acessar contas reais: dois anúncios → duas origens; mensagem sem referral preserva a anterior; tamanho disponível+intenção de reservar → qualificado; pedido sem pagamento → nenhuma venda; pedido+pagamento confirmados → compra com valor/moeda; notificação repetida ou concorrente → um único marco; timeout após possível envio → resultado desconhecido sem repetição automática. Inclua autenticação inválida, consulta Meta negada e respostas fora de ordem.

Depois descreva a validação autorizada em ambiente separado, com dados de teste isolados de produção. Confira uma compra real autorizada recebida pela Meta, com valor e moeda correspondentes, sem disparar de novo um marco já enviado. Oriente o Gerenciador de Eventos e a aba Testar eventos; test_event_code sozinho não isola dados fictícios e eventos de teste podem ser usados pela Meta. Termine com um relatório esperado → observado e os itens pendentes. Recebimento, atribuição e otimização são verificações diferentes; não declare conclusão com base apenas no código gerado.