Documentação
Sign inGet started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Criando templates WhatsApp

O catálogo gerenciado do Bird cobre os casos comuns, mas um template escrito com suas próprias palavras precisa ser criado em uma WhatsApp Business Account que você tenha conectado. Esta página cobre a criação de um template; Templates WhatsApp cobre como navegar e enviar o que já existe.
Três coisas definem todo o fluxo:
  • Um template contém versões, e uma versão contém uma entrada por idioma. O que realmente é enviado é um idioma de uma versão, não o template.
  • O conteúdo é escrito em um rascunho. Um template tem no máximo um rascunho aberto, e nada nele chega ao WhatsApp até você enviá-lo.
  • A aprovação retorna por idioma. Um idioma pode ser aprovado enquanto outro na mesma versão é rejeitado.

Antes de começar

Você precisa de um número próprio conectado, que é o que dá ao seu espaço de trabalho uma WhatsApp Business Account para criar templates. Uma conta que você não conectou é recusada, assim como editar um dos templates bird_ integrados do Bird: eles ficam na conta própria do Bird, então duplique um para a sua conta.
Criar um template de autenticação também exige um negócio verificado; utility e marketing não exigem. Consulte Templates de autenticação para esse requisito.
Crie um template no dashboard em WhatsApp > Templates, com a bird CLI, ou pelo servidor MCP. O dashboard segue os mesmos passos que esta página descreve; os exemplos mais adiante usam a CLI.

No dashboard

New template oferece duas formas de começar. Start with a template abre a galeria, o caminho mais rápido: escolha um que já diga quase o que você precisa, incluindo um do Bird, e a cópia aparece na sua conta como um rascunho aberto.
A galeria de templates no dashboard do Bird: uma grade de cartões de template, cada um com a pré-visualização da mensagem e identificado com nome, slug, status, categoria e idiomas, ao lado de filtros por origem do template, categoria e idioma
Start from scratch pede a categoria, um nome e um idioma padrão antes de abrir o editor. Um template de marketing também escolhe um tipo de mensagem. O nome se torna o slug, e o slug e a categoria são as duas escolhas que você não pode alterar depois.
O passo Criar um novo template no dashboard do Bird: blocos de categoria Marketing, Utility e Authentication acima de um campo Nome e um seletor de Idioma padrão, com um botão Criar template
O editor escreve um idioma por vez: a barra lateral lista os idiomas do template com o estado de revisão de cada um, a coluna central contém o conteúdo, e a pré-visualização no celular renderiza a mensagem com valores de exemplo substituídos.
O editor de templates no dashboard do Bird para o template utility Order update: English marcado como Approved ao lado de Dutch na barra lateral de idiomas, e uma pré-visualização no celular da mensagem renderizada com seus botões Track order e Contact support
O editor muda de forma conforme o template. Um carrossel adiciona uma aba por cartão ao lado da mensagem, e cada cartão precisa repetir a estrutura do cartão 1: o mesmo formato de cabeçalho e os mesmos botões na mesma ordem.
O editor de templates no dashboard do Bird para um template de marketing com carrossel: abas Message, Card 1, Card 2 e Card 3 acima do corpo da mensagem, com uma seção Variable samples abaixo, ao lado de uma pré-visualização no celular mostrando a mensagem seguida de cartões de imagem deslizáveis, cada um com um botão Show me
Um template de autenticação não tem editor de mensagem. O WhatsApp escreve o texto, então o editor oferece apenas as duas configurações a partir das quais ele escreve: Add security recommendation e Code expiration (minutes).
O editor de templates no dashboard do Bird para um template de autenticação: um painel Authentication settings com um toggle Add security recommendation e um campo Code expiration (minutes), ao lado de uma pré-visualização no celular da mensagem de código de verificação que o WhatsApp escreve, com seu botão Copy code
Save as draft salva seu trabalho sem contatar o WhatsApp. Submit for review congela a versão e a envia para o WhatsApp. O submit da CLI, abaixo, realiza o mesmo congelamento.

Duas formas de começar

Duplicar um template existente

Uma duplicação traz o conteúdo da origem como um rascunho aberto e chama o WhatsApp zero vezes, então nada é enviado até você decidir. Duas coisas sobre uma cópia valem saber antes de fazer uma:
  • A categoria é herdada e não pode ser alterada. Se você precisar de uma categoria diferente, comece do zero.
  • Você pode reduzir os idiomas, nunca adicionar. Um template de catálogo com 70 idiomas não precisa se tornar 70 idiomas seus: escolha o subconjunto que você vai realmente manter. Pedir um idioma que a origem não possui é recusado com E15060, e a resposta informa quais não corresponderam. Adicione outros idiomas à cópia depois.
O subconjunto de idiomas é um array, então ele vai no corpo da solicitação em vez de um flag:
Exemplo de código
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Exemplo de código
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Omita include_languages e a cópia leva todos os idiomas da origem. Omita default_language e a cópia mantém o idioma padrão da origem quando seu subconjunto ainda o inclui; caso contrário, ela usa o primeiro dos idiomas da cópia por tag canônica, que não é necessariamente o primeiro que você listou, então defina explicitamente se isso importar.

Começar do zero

Criar um template requer um slug, uma conta, uma categoria e um idioma padrão:
Exemplo de código
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
O slug e a categoria são permanentes. O WhatsApp deriva seu próprio nome de template a partir do slug, e nem ele nem a categoria podem ser alterados depois; um diferente significa um novo template. O prefixo bird_ é reservado para o catálogo do Bird. A categoria que você escolher não é necessariamente o que determina o preço de um envio: a Meta aplica sua própria categoria por idioma e pode alterá-la, e o preço segue o da Meta.

Escrevendo cada idioma

Abra o rascunho e então escreva um idioma por vez:
Exemplo de código
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Abrir um rascunho pode ser repetido com segurança: um template tem apenas um, então isso retorna o rascunho aberto em vez de criar um segundo. O template também o reporta como draft_version_id.
Escrever um idioma substitui o idioma, não faz merge. O arquivo carrega o components completo daquele idioma toda vez, então leia o idioma primeiro e escreva-o de volta inteiro; enviar apenas o bloco que você alterou apaga o resto.
Toda variável precisa de um valor de exemplo. O WhatsApp revisa a mensagem preenchida e não o template, então um bloco com placeholders e sem parâmetros de exemplo é recusado no submit, não no momento da escrita.

Verificar e então enviar

Valide antes de congelar qualquer coisa. Um submit somente de validação executa todas as verificações em todos os idiomas e reporta cada problema em uma passagem, sem enviar nada ao WhatsApp:
Exemplo de código
bird whatsapp templates versions submit order_update <version-id> --validate-only
Leia valid e errors; cada erro nomeia o idioma, o campo e o código com o qual um submit real falharia. Então envie de verdade removendo o flag. Isso congela o rascunho como uma versão imutável e responde 202. Use uma chave de idempotência diferente para a verificação e o submit, já que reutilizar uma chave com um corpo alterado é rejeitado.
Apenas idiomas cujo conteúdo difere da cópia aprovada vão para o WhatsApp. Um que já corresponde carrega sua aprovação adiante, então um submit em que nada mudou é resolvido imediatamente sem nada para consultar. Nenhum rascunho substituto é aberto depois: a próxima rodada de edições começa criando um rascunho novamente.
Uma execução limpa somente de validação não prevê a decisão do WhatsApp. O WhatsApp não oferece como perguntar antecipadamente, então ele ainda pode recusar conteúdo que passou em todas as verificações locais.

Acompanhando a revisão

A aprovação chega depois e por idioma. O pending_version_id do template permanece definido enquanto qualquer idioma não está resolvido, e a lista por idioma traz cada veredito:
  • approved envia. available_languages no template é exatamente o que um envio pode resolver agora.
  • rejected, submit_failed, paused precisam de uma edição em um novo rascunho. WhatsApp aceita uma edição em um idioma pausado, e reenviar é o que o libera.
  • disabled, limit_exceeded, in_appeal recusam uma edição completamente; eles só precisam ser relidos até que o WhatsApp os mova.
O status próprio do template é um agregado: active significa que pelo menos um idioma pode ser enviado, não todos.

Enviando o que você criou

Um template criado por você envia pelo mesmo endpoint que qualquer outro, com uma diferença em relação ao catálogo do Bird: você deve informar from, e ele precisa ser um número na mesma WhatsApp Business Account do template. Um remetente em uma conta diferente é recusado 422 E15023 antes de qualquer cobrança.
Um template pode exigir um idioma do destinatário por meio de language_source_required. Caso contrário, on_missing_language controla se a resolução falha ou pode usar um idioma base aprovado ou default_language. Teste a política configurada contra os available_languages aprovados do template; um idioma padrão não aprovado não pode ser enviado. Os valores que você fornecer precisam preencher os placeholders de qualquer idioma que realmente for resolvido, então leia o conteúdo desse idioma antes de enviar. Consulte Enviando mensagens WhatsApp para o payload completo.

Pontos de atenção

  • A versão mais recente não é a que envia. Uma lista de versões é ordenada da mais recente para a mais antiga e inclui qualquer rascunho aberto, então a primeira linha geralmente é um rascunho ou uma versão ainda em revisão. O template nomeia a versão em serviço como live_version_id; um template sem versão ativa não pode ser enviado.
  • Um idioma em revisão recusa uma escrita. O WhatsApp o mantém até a revisão terminar, então uma edição durante pending falha em vez de entrar em fila.
  • Uma linha da lista não traz conteúdo. Listar templates os encontra e mostra o estado do ciclo de vida; ler o que um template realmente diz exige uma leitura de versão.
  • Excluir é irrecuperável. Descartar um idioma, excluir um rascunho e excluir um template exigem uma confirmação explícita, e excluir um template interrompe todo envio por aquele slug.

Próximos passos

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoWhat is a WhatsApp message template?Explore a funcionalidadeWhatsApp templatesSiga o percurso de aprendizagemBuild your first integration
Experimente na prática e obtenha um resumo de implementação