Governança de templates em times grandes

O WhatsApp Business Account (WABA) e compartilhado, e o namespace de templates tambem. Quando marketing, suporte e produto criam templates no mesmo painel sem coordenacao, os sintomas aparecem rapido. Dois times criam "atualizacao_pedido" com copy ligeiramente diferente e ninguem sabe qual usar. Alguem reaproveita o nome errado em producao. Marketing submete um template promocional classificado como utility para fugir da regra de cobranca e a Meta rejeita ou reclassifica. Produto cria um template de teste que nunca foi removido e polui a lista.

A raiz do problema e que o painel da Meta trata templates como recursos globais do WABA, sem nocao de dono, sem historico de versao e sem ambiente de homologacao. Cada criacao manual e uma decisao isolada que afeta todos os times. Sem governanca, o resultado e duplicacao, rejeicoes recorrentes, custo inflado por categoria errada e um namespace impossivel de auditar.

A primeira defesa e um padrao de nomes que torne o dono, a jornada e o idioma obvios no proprio nome do template. A Meta so aceita minusculas, numeros e underscore, entao o padrao precisa caber nessa restricao. Um esquema que funciona bem e prefixo por time, depois jornada, depois idioma, depois versao: time_jornada_idioma_versao. Exemplo: support_orderupdate_pt_v2.

Com esse padrao, support_orderupdate_pt_v2 se le sozinho: e do suporte, trata atualizacao de pedido, em portugues, segunda versao. O prefixo de time elimina conflito de nomes entre equipes, porque cada uma so cria dentro do seu proprio espaco. As regras minimas que sustentam a convencao:

• Prefixo de time obrigatorio: nenhum template existe sem dono explicito no nome.
• Uma jornada por template: nao misture confirmacao de pedido e pesquisa de satisfacao no mesmo nome.
• Idioma sempre no nome: variantes de locale sao templates distintos, nunca o mesmo template com texto trocado na mao.
• Versao no sufixo: mudou conteudo, estrutura ou categoria, sobe a versao em vez de editar o template antigo.
• Sem nomes de teste em producao: temp, teste, copy e final ficam fora do WABA de producao.

Um template nao e estatico: ele nasce como rascunho, passa por revisao interna, vai para aprovacao da Meta, entra em uso e um dia e aposentado. Tratar esse ciclo de forma explicita evita que rascunhos vazem para producao e que templates mortos continuem na lista. Cada transicao tem um responsavel e um criterio claro de passagem.

  draft
    |  copy escrita, revisao interna de texto e variaveis
    v
  review
    |  aprovacao de copy + checagem de categoria correta
    v
  submit Meta
    |  envio via Graph API; aguarda analise da Meta
    v
  approved
    |  Meta aprovou; ainda nao em uso
    v
  active
    |  em producao, recebendo trafego
    v
  deprecated
       substituido por nova versao; mantido so para auditoria

O ponto chave do versionamento e que aprovado pela Meta nao significa editavel. Mudou a copy de support_orderupdate_pt_v2? Crie support_orderupdate_pt_v3, submeta, valide e so entao mova o trafego. O v2 vira deprecated, nao desaparece: ele fica como registro do que estava no ar quando uma mensagem foi enviada. Editar template aprovado no painel quebra o historico e costuma forcar nova analise da Meta de qualquer forma.

Governanca exige separar quem cria de quem submete. Qualquer pessoa do time dono pode propor um template, mas a submissao para a Meta passa por um portao com revisao de copy e checagem de categoria. Esse portao e o que impede tanto o texto fora de politica quanto o erro de categoria que estoura o custo.

1. Criacao (autor do time dono): redige a definicao no formato de codigo, define variaveis, idioma e a categoria pretendida. Nada vai direto para a Meta nesse passo.
2. Revisao de copy (revisor designado): confere clareza, tom, conformidade com a politica do WhatsApp e ausencia de conteudo que motive rejeicao. Aprova ou devolve com comentarios.
3. Checagem de categoria (responsavel de governanca): valida se a categoria esta correta. Confirmacao e atualizacao ligada a uma acao do usuario e utility; promocao e reengajamento e marketing. Classificar marketing como utility para pagar menos e reclassificado pela Meta e mina a confianca do WABA.
4. Submissao (papel autorizado): so um conjunto restrito de pessoas tem permissao de submeter via API. Esse passo registra quem submeteu, quando e qual versao.
5. Validacao pos-aprovacao (autor + governanca): ao voltar approved da Meta, faz um envio de teste, confere render de variaveis e botoes, e so entao promove para active.

A checagem de categoria merece destaque porque e onde governanca vira dinheiro. Utility costuma ser mais barata que marketing, e a tentacao de rotular tudo como utility e real. A Meta detecta o padrao, reclassifica e, em caso reincidente, pode prejudicar a qualidade do numero. O portao de categoria protege o orcamento e a reputacao ao mesmo tempo.

Criar template manualmente no painel da Meta nao escala nem audita. A alternativa e tratar template como codigo: a definicao vive em um repositorio versionado, passa por pull request (a revisao de copy e a checagem de categoria viram revisao de PR) e e sincronizada para a Meta via Graph API. O painel deixa de ser a fonte da verdade; o repositorio passa a ser. Cada mudanca tem autor, diff, historico e rollback.

# templates/support_orderupdate_pt_v2.yaml
# A definicao versionada e a fonte da verdade. O painel da Meta
# e apenas um reflexo deste arquivo, sincronizado via Graph API.
name: support_orderupdate_pt_v2
language: pt_BR
category: UTILITY            # utility: atualizacao ligada a acao do usuario
owner: support
components:
  - type: BODY
    text: "Ola {{1}}, seu pedido {{2}} mudou para o status: {{3}}."
    example:
      body_text:
        - ["Joao", "#10482", "enviado"]
  - type: BUTTONS
    buttons:
      - type: URL
        text: "Acompanhar pedido"
        url: "https://exemplo.com/pedidos/{{1}}"
        example: ["https://exemplo.com/pedidos/10482"]

A sincronizacao le o arquivo e cria ou atualiza o template no WABA via Graph API. O mesmo script roda em CI: ao mergear o PR, o template e submetido a Meta e o pipeline registra o status retornado.

// sync-template.js
// Le a definicao YAML e submete o template a Meta via Graph API.
// Rode no CI apos o merge do PR que aprovou a copy e a categoria.
import fs from 'node:fs';
import yaml from 'js-yaml';

const WABA_ID = process.env.WABA_ID;
const TOKEN = process.env.META_TOKEN;

async function syncTemplate(path) {
  const def = yaml.load(fs.readFileSync(path, 'utf8'));

  const payload = {
    name: def.name,
    language: def.language,
    category: def.category,
    components: def.components,
  };

  const res = await fetch(
    `https://graph.facebook.com/v21.0/${WABA_ID}/message_templates`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    },
  );

  const data = await res.json();
  if (!res.ok) {
    // status de rejeicao da Meta volta aqui: logue e falhe o pipeline
    throw new Error(`Falha ao sincronizar ${def.name}: ${JSON.stringify(data)}`);
  }
  // data.status costuma ser PENDING ate a Meta analisar
  console.log(`Submetido ${def.name}: status ${data.status}`);
  return data;
}

syncTemplate(process.argv[2]).catch((err) => {
  console.error(err);
  process.exit(1);
});

Com essa base, todo o processo de aprovacao acontece na revisao do PR e a Meta recebe apenas o que ja passou pelos portoes. O namespace fica auditavel: para saber por que um template existe, quem o criou e o que mudou entre versoes, basta olhar o historico do repositorio.

Governanca nao termina na aprovacao. Cada template ativo precisa ser medido para saber se ainda merece existir. As metricas que importam vem da propria Meta (status de entrega e leitura) e do seu produto (resposta e bloqueio), e devem ser acompanhadas por template, nao em agregado.

• Taxa de entrega: proporcao de mensagens entregues sobre enviadas. Queda persistente sugere numero invalido na base, bloqueio ou problema de qualidade do template.
• Taxa de leitura: proporcao de entregues que foram lidas. Leitura baixa em utility pode indicar copy irrelevante ou disparo na hora errada.
• Taxa de resposta: proporcao que gerou resposta do cliente. Em templates que esperam acao (confirmar, agendar), e o sinal mais direto de eficacia.
• Taxa de bloqueio e denuncia: proporcao de destinatarios que bloquearam ou marcaram como spam. Em templates de marketing, e o indicador critico: alto bloqueio derruba a qualidade do numero e ameaca todos os times do WABA.

A leitura cruzada e o que orienta a decisao de manter, revisar ou aposentar. Um template de marketing com leitura ok mas bloqueio subindo deve ser pausado antes que prejudique o WABA inteiro. Um utility com entrega caindo aponta para higiene de base. Medir por template fecha o ciclo de governanca: o que entra pelo portao de aprovacao tambem sai por um criterio de dados quando para de servir.