Appearance
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
| Campo | Função |
|---|---|
| Objetivo e conversão final | Define o resultado de negócio e o evento verificável no produto. Um lead pode ser etapa intermediária. |
| Persona e momento | Separa mensagens quando um projeto atende públicos com tarefas distintas. |
| Oferta e prova | Registra funcionalidades, condições, preço, depoimentos e disponibilidade confirmados, com fonte e data. |
| Jornada e destino | Liga post ou anúncio à página, cadastro, atendimento e resultado final. |
| Área e elegibilidade | Limita regiões, horários, capacidade ou outros requisitos que mudam a viabilidade da campanha. |
| Conteúdo e criativos | Propõe argumentos, formatos e CTAs adequados a cada canal. |
| Experimento | Define uma hipótese por variação, janela de observação, volume mínimo útil e métrica de decisão. |
| Orçamento | Inclui verba de mídia, teto diário, duração, moeda e regras para pausas ou expansão. |
| Critério de avanço | Define 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.
| Capacidade | Uso no módulo | Limite ou cuidado |
|---|---|---|
| Graph API de Páginas e Instagram | Publicaçõ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 API | Ler 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 Insights | Gasto, 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 existente | Reutilizar 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 API | Conectar 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 leads | Receber 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 personalizados | Retargeting 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évias | Comparaçã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_strategypor 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
marketingcom 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.0e insightsv23.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_idquando 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,ResultadoseConexão Metapor 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.