Skip to content

Inteligência de campanhas e mídia social do Atpares ​

Este documento define o motor geral para analisar cada projeto, propor campanhas, estimar quais posts têm potencial de distribuição, recomendar anúncios e aprender com resultados. Público, oferta, região, orçamento, evento de sucesso e mensagens pertencem à estratégia de cada projeto. O Atpares não embute uma campanha fixa de uma marca no próprio motor.

Resultado esperado ​

Para cada projeto, o Atpares deve entregar uma proposta revisável com diagnóstico, objetivo de negócio, persona, jornada, hipótese, mensagem, canais, destino, plano de conteúdo, plano de testes, configuração sugerida de mídia, métricas, orçamento e condições de escala. Cada recomendação informa a evidência usada, sua data, a amostra, o grau de confiança e os dados que ainda faltam. A estratégia tem versões para que resultados futuros possam ser ligados à hipótese original.

O motor consulta a base de conhecimento do projeto, fontes verificadas, disponibilidade atual de recursos, posts publicados, desempenho orgânico, campanhas pagas, eventos do produto e limites de gasto. Claude estrutura a proposta e redige copy com apoio dessas evidências; Gemini produz mídia conforme a direção aprovada e o fluxo visual existente. Validações determinísticas bloqueiam afirmações sem fonte, destino quebrado, evento ausente, identidade incorreta e orçamento fora do limite.

Modelo de estratégia por projeto ​

CampoFunção
Objetivo e conversão finalDefine o resultado de negócio e o evento verificável no produto. Um lead pode ser etapa intermediária.
Persona e momentoSepara mensagens quando um projeto atende públicos com tarefas distintas.
Oferta e provaRegistra funcionalidades, condições, preço, depoimentos e disponibilidade confirmados, com fonte e data.
Jornada e destinoLiga post ou anúncio à página, cadastro, atendimento e resultado final.
Área e elegibilidadeLimita regiões, horários, capacidade ou outros requisitos que mudam a viabilidade da campanha.
Conteúdo e criativosPropõe argumentos, formatos e CTAs adequados a cada canal.
ExperimentoDefine uma hipótese por variação, janela de observação, volume mínimo útil e métrica de decisão.
OrçamentoInclui verba de mídia, teto diário, duração, moeda e regras para pausas ou expansão.
Critério de avançoDefine quando passar de aprendizado para escala ou de uma persona para outra.

Os eventos de conversão vêm de um contrato com cada produto. Contrasync pode medir ativação em uma jornada de contrato; Drawgg, configuração e primeira interação; Prompteira, uso ou publicação de prompt. A métrica final só entra em produção quando o fluxo correspondente estiver confirmado. Projetos de dois lados podem exigir um limite mínimo de oferta antes de investir na demanda; esse limite pertence à estratégia configurada pelo projeto.

Seleção de posts e distribuição ​

Antes da publicação, o Atpares estima potencial com base em persona, assunto, novidade, clareza, formato, canal, horário observado, histórico comparável e qualidade do destino. A saída é uma faixa de confiança e uma explicação. Sem base suficiente, o estado é dados insuficientes; uma porcentagem exata sem calibração histórica não deve ser exibida.

Depois da publicação, quando a API permitir, coleta séries em 2 h, 24 h, 72 h e 7 dias. Compara posts da mesma conta, formato, persona, idade e janela. Considera alcance ou visualizações com rótulo correto, retenção, compartilhamentos, salvamentos, comentários relevantes, cliques e avanço na jornada. Corrige a incerteza de amostras pequenas e não transforma um pico inicial em prova de desempenho futuro.

O resultado da triagem é promover post existente, criar anúncio novo, testar mais ou não investir. A decisão verifica direitos de imagem, veracidade, CTA, destino, formato e elegibilidade do post para anúncio. Um post de grande alcance pode exigir outro criativo quando o objetivo é aquisição. Métricas orgânicas e pagas permanecem separadas; alcance de redes ou períodos diferentes não é somado como pessoas únicas.

O aprendizado guarda hipótese, versão do criativo, público, orçamento, atribuição, resultados e motivo de decisão. O Atpares testa novas mensagens dentro de um limite configurado e concentra investimento após evidência de qualidade e custo por conversão final. Previsões são recalibradas contra resultados observados por projeto e formato.

Recomendações de Meta Ads ​

O Atpares propõe a hierarquia campanha, conjunto, criativo e anúncio; objetivo compatível com a conversão; local de conversão; público e área; posicionamentos; estratégia de lance; orçamento; duração; evento de otimização; criativos e destino. A interface mostra os campos exatos, a prévia, a conta e a estimativa de gasto antes da aprovação. O objetivo de Leads (OUTCOME_LEADS) serve a jornadas de captação mensuráveis; Reconhecimento (OUTCOME_AWARENESS) serve à cobertura quando essa é a finalidade. Esses objetivos constam na coleção oficial da Meta. Combinações válidas de campos dependem da versão da API, conta, ativos, posicionamento e evento.

O menor custo é observado para uma métrica e uma restrição: por exemplo, alcance qualificado em determinada área ou custo por conversão final com um teto de gasto. A estimativa de audiência é um auxílio ao planejamento e não garante alcance entregue, CPM ou conversões. O painel mostra custo por mil pessoas alcançadas, frequência e métricas de aquisição em paralelo quando relevante.

Campanhas novas nascem PAUSED. Criar, alterar ou ativar gasto exige aprovação registrada do proprietário no Atpares, com conta, área, objetivo, orçamento, teto, duração e diferenças da versão anterior. Uma regra de operação previamente autorizada pode pausar por teto, tracking indisponível ou destino quebrado. A API usa idempotência, reconcilia criações parciais e audita cada mutação. Campanhas externas são inicialmente importadas para leitura.

Capacidades das APIs da Meta ​

O Atpares já possui conexões de Facebook e Instagram, recibos de publicação e post_metrics. A conexão da conta de anúncios deve ter credencial e estado próprios, com verificação de permissões e de vínculo entre conta, Página, Instagram e fonte de eventos. A coleção oficial documenta a hierarquia dos anúncios e Ads Insights.

CapacidadeUso no móduloLimite ou cuidado
Graph API de Páginas e InstagramPublicações, identidade, links e métricas orgânicas.Campos variam por tipo de mídia e versão. O reach atual do Facebook usa post_total_media_view_unique; exibir visualizadores únicos de mídia até confirmar métrica equivalente a alcance.
Marketing APILer conta, campanha, conjunto, criativo, anúncio, orçamento, status e prévias; criar rascunhos pausados.ads_read para leitura e ads_management para escrita, além de acesso aos ativos e revisão quando aplicável. Acesso oficial.
Ads InsightsGasto, alcance, frequência, impressões, CPM, CTR, cliques de saída, ações e custo por ação por nível e período.Alguns campos e recortes são incompatíveis. Paginar, guardar janela, moeda, fuso, versão e instante da coleta. Exemplo oficial.
Criativo com post existenteReutilizar post elegível e vincular publicação, criativo e anúncio.object_story_id é documentado para Facebook; validar o caminho de mídia existente do Instagram por formato e conta. Exemplo oficial.
Pixel e Conversions APIConectar eventos web, app ou servidor ao resultado no produto e deduplicar quando necessário.Exige implementação no produto, privacidade e qualidade de correspondência. O SDK oficial cobre eventos web, app e offline.
Formulários e webhooks de leadsReceber lead, origem e horário quando formulário instantâneo for usado.Precisa de permissão, configuração e retorno de qualidade do CRM.
Públicos de engajamento ou personalizadosRetargeting e exclusão de convertidos quando houver volume, consentimento e elegibilidade.Não presumir tamanho mínimo atingido nem usar segmentação sensível.
Experimentos, estimativas e préviasComparação controlada, planejamento de cobertura e revisão do criativo.Descobrir capacidade por conta e objetivo. Estimativas não são resultados.

A Biblioteca de Anúncios pode fornecer exemplos públicos de mensagem, com fonte e data. Ela não mostra custo por aquisição nem conversões de concorrentes; duração de anúncio não prova que ele venceu. Pesquisa comercial fora da cobertura da API oficial deve ser revisão manual, sem scraping como dependência do motor.

Implementação de ponta a ponta ​

Fase 0. Contrato de estratégia e eventos ​

  • Criar marketing_strategy por projeto com objetivo, persona, jornada, evento final, restrições, orçamento, evidências, versão e aprovador.
  • Definir ingestão de eventos mínimos do produto: ID estável, tipo, instante, projeto, campanha ou clique quando conhecido, estado e dimensões úteis. Guardar dados pessoais no produto/CRM sempre que possível.
  • Definir janela de atribuição, deduplicação, retenção, consentimento e comportamento quando o produto não emitir eventos.
  • Aceite: reproduzir uma jornada de teste até a conversão final, sem eventos duplicados ou atribuição inventada.
  • Estado: implementada como quadro de estratégia lido pela IA todo dia, com posicionamento, diagnóstico do conteúdo e fila de impulsionamento com valor por post. Regras em Quadro de estratégia.

Fase 1. Conexão e coleta ​

  • Adicionar módulo NestJS marketing com cliente Meta, descoberta de capacidades, repositório de campanhas e coletor de Insights, aproveitando criptografia e autorização existentes.
  • Salvar conexão de anúncio por projeto, ID da conta, Página, identidade Instagram, fonte de eventos, permissões, moeda, fuso e estado. Versionar Graph/Marketing API por configuração; o app usa hoje META_GRAPH_VERSION=v21.0 e insights v23.0.
  • Importar campanhas existentes em leitura. Guardar snapshots de configuração, métricas por dia e vínculos entre post, criativo, anúncio, conjunto e campanha. Tratar paginação, rate limit, respostas parciais e retry idempotente.
  • Aceite: exibir capacidades faltantes e conciliar gasto de 30 dias com o relatório Meta da mesma conta, moeda e janela.

Fase 2. Atribuição e qualidade ​

  • Implementar ingestão autenticada de eventos do produto, com assinatura, fila, tentativas e chave de idempotência. Cada produto implementa Pixel, Conversions API ou eventos de aplicativo conforme sua jornada; deduplicar com event_id quando Pixel e servidor reportarem o mesmo evento.
  • Relacionar campanha e anúncio a cliques, etapas de funil, conversão final e razões de perda. Mostrar a fonte de cada número e divergência entre atribuição da Meta e observação do produto.
  • Integrar formulário instantâneo e webhook somente quando esse canal for usado pelo projeto.
  • Aceite: lead sem conversão final aparece como etapa intermediária; eventos repetidos e falhas de webhook são tratados sem inflar resultados.

Fase 3. Planejamento e ranking ​

  • Acrescentar estratégia estruturada à direção de projeto, mantendo conhecimento e regras editoriais. Gerar hipóteses, plano de teste, copy e CTA com evidências verificadas.
  • Criar previsão pré-publicação e avaliação pós-publicação por rede, formato, persona e objetivo. Guardar sinais, faixa de confiança, explicação e versão do modelo. Avaliar com histórico sem usar dados futuros.
  • Gerar uma ficha por post com elegibilidade, ação recomendada, objetivo, público, destino, orçamento máximo e motivo.
  • Aceite: falta de histórico aparece como incerteza; alcance alto sem conversão não vira vencedor automático de aquisição.

Fase 4. Execução assistida ​

  • Adicionar páginas Vue Campanhas, Plano, Posts candidatos, Resultados e Conexão Meta por projeto, ligadas à fila de publicações.
  • Expor rotas autenticadas para estratégia, recomendações, planos, rascunhos, aprovação, ativação, pausa e Insights. Antes de ativar, reconferir conta, orçamento, destino, evento e aprovação.
  • Criar campanha, conjunto, criativo e anúncio pausados; reconciliar IDs após erro parcial e registrar auditoria. Limitar gasto por projeto e conta.
  • Aceite: requisições repetidas não duplicam anúncios; nenhum anúncio nasce ativo sem aprovação; falhas parciais permitem retomar.

Fase 5. Aprendizado e extensão ​

  • Coletar Insights e eventos diariamente; recomendar manter, pausar, revisar criativo ou ampliar gradualmente. Alertar sobre gasto sem conversão, frequência crescente, tracking atrasado e destino indisponível.
  • Testar com um projeto piloto; revisar métricas finais, custo, cobertura e erros semanalmente. Só então aplicar estratégias próprias aos demais projetos.
  • Aceite: relatório de 30 dias explica gasto, hipóteses, resultados, limites de atribuição e próximo teste.

Persistência e qualidade ​

Criar tabelas para marketing_strategies, marketing_funnels, marketing_events, meta_ad_connections, meta_campaign_drafts, meta_entities, meta_insight_snapshots, marketing_post_scores, marketing_recommendations e marketing_actions. Toda linha tem project_id e escopo do proprietário; IDs externos são únicos por conta. Snapshots guardam período, nível, moeda, fuso, atribuição e instante da coleta. Preservar post_metrics e publication_posts nas migrations.

Testar contratos de payload Meta, deduplicação, autorização entre projetos, orçamento, idempotência e retomada após falha. Monitorar token vencido, permissão recusada, rate limit, atraso de Insights e divergência de gasto. Não registrar tokens ou dados pessoais nos logs.

Configuração necessária por projeto ​

O produto solicita, no momento adequado, objetivo, persona, evento final, oferta confirmada, destino, área ou capacidade, orçamento e teto, ativos Meta, responsáveis pela conversão e critérios de avanço. Credenciais são conectadas pelo fluxo de autorização, sem pedir token em texto. Esses dados personalizam a estratégia; o motor técnico permanece comum.