Sign inGet Started

Templates de autenticação do WhatsApp

Um template de autenticação entrega um código de verificação de uso único. A Meta fornece o texto quando você cria o template. Ao enviá-lo, informe o código como parâmetro do corpo.

Antes de enviar

Escolha entre usar um template gerenciado pelo Bird ou criar um template na sua própria conta empresarial.

O envio dos templates de catálogo do Bird, bird_otp e bird_otp_authifly, não exige nenhuma verificação da sua parte. Esses templates ficam nas próprias contas WhatsApp Business do Bird, e o envio gerenciado nunca consulta o status de verificação da sua empresa.

Quando a conta empresarial conectada informa not_verified, o Bird recusa a criação ou duplicação de templates de autenticação com 412 E15043 WhatsAppTemplateBusinessNotVerified. Confira a conta conectada e o status sincronizado mais recente dela. Consulte Verificação de empresa do WhatsApp para conhecer o processo de verificação e o tratamento de cada status.

Essa exigência não afeta a criação de templates de utilidade e de marketing; você pode continuar criando e editando esses templates, qualquer que seja o seu status de verificação.

Crie templates no dashboard, com a bird CLI ou pelo servidor MCP. Consulte Criação de templates de autenticação para ver o fluxo completo.

Como enviar um código de verificação

POST /v1/whatsapp/messages com um objeto template que indica um slug do catálogo:

const msg = await bird.whatsapp.send({
  to: "+14155550100",
  template: {
    slug: "bird_otp",
    language: "en",
    parameters: { code: "481920" },
  },
});
console.log(msg.id, msg.status);

Quatro regras são específicas desta categoria:

  • Omita from. Um template gerenciado pela Bird escolhe o próprio remetente com base na categoria e na região, então definir from retorna 422 E15018 WhatsAppSenderNotAllowed. É o contrário de um envio de formato livre, que exige from, algo importante se você vem das páginas de mensagens interativas.
  • to deve ser um número de telefone E.164. Um template de autenticação não pode ser enviado para um ID de usuário restrito à empresa; isso retorna 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
  • O código vai em parameters.code. Ele preenche o placeholder do corpo e o botão de copiar código. Um envio components, por outro lado, recebe exatamente um parâmetro posicional no corpo: o código. Enviar zero parâmetros, ou nomear o parâmetro, retorna 422 E15003 WhatsAppTemplateParameterMismatch.
  • Não é necessária uma janela de atendimento ao cliente. Envios de template não dependem da janela, e é justamente por isso que existe um template de código de verificação: ele precisa alcançar alguém que nunca enviou mensagem para você.

Consulte os idiomas disponíveis para bird_otp ou bird_otp_authifly no catálogo de templates. Se o idioma solicitado não estiver disponível, o envio falha em vez de usar outro idioma.

O botão de copiar código

A Meta escreve o corpo de um template de autenticação como um texto predefinido com um único placeholder para o código, então você fornece flags em vez de texto. Um envio parameters preenche o botão a partir de code. Em um envio components, o componente de botão é opcional: se você não incluí-lo, a Bird o adiciona com o mesmo código do corpo. Você também pode fornecê-lo:

Exemplo de código
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }

Em ambos os casos, exatamente um botão chega ao WhatsApp, e é o botão de copiar código: tocar nele copia o código para a área de transferência. A Bird oferece suporte apenas a copy_code; os outros dois comportamentos de botão que a Meta documenta para templates de autenticação, preenchimento automático com um toque e sem toque, não estão disponíveis na Bird.

A criação do botão de um template segue o mesmo formato: um botão otp, e o template não aceita nenhum outro tipo de botão. Em vez de escrever o texto, você fornece add_security_recommendation (um booleano exibido no corpo) e code_expiration_minutes (de 1 a 90, exibido no rodapé).

O que a Meta permite em um template de autenticação

A Meta define a estrutura de um template de autenticação e revisa seu conteúdo: nenhum URL, mídia ou emoji em qualquer parte do template, e um limite de 15 caracteres no parâmetro do código. A categoria também muda a forma como o WhatsApp entrega a mensagem, que vai apenas para o dispositivo principal do destinatário. Consulte as Diretrizes de templates para ver a estrutura fixa, os limites de caracteres e o processo de revisão completos.

Custo

A categoria e o destino definem o preço. Consulte Tarifas de autenticação internacional do WhatsApp para saber como o envio para um país diferente da sua localização principal pode alterá-lo, e Custo e faturamento para saber quando um envio é cobrado. Os valores das tarifas estão em Preços do WhatsApp.

Pontos de atenção

  • Os templates prontos do Bird não são entregues em nove países. bird_otp e bird_otp_authifly são enviados pelas próprias contas WhatsApp Business do Bird, e essas contas não entregam mensagens de autenticação para Egito, Índia, Indonésia, Malásia, Nigéria, Paquistão, Arábia Saudita, África do Sul ou Emirados Árabes Unidos. Esse envio é recusado com 422 E15063 WhatsAppDestinationRestricted antes de qualquer cobrança. Um template criado na sua própria conta e enviado pelo seu próprio número chega a esses países normalmente. O Verify também chega a eles, transferindo o código de verificação para outro canal automaticamente.
  • Um envio de template próprio exige from, e ele precisa estar na mesma conta WhatsApp Business que o template. Um remetente em outra conta é recusado com 422 E15023 WhatsAppSenderWABAMismatch antes de qualquer cobrança.
  • Só é possível enviar um idioma cuja versão esteja aprovada e ativa. Um idioma em rascunho, pendente, rejeitado ou pausado não pode ser enviado.
  • A Meta pode recategorizar um template por iniciativa própria. Não é possível recusar, e a mudança altera as regras de preço e de entrega associadas à categoria.
  • A categoria do template e a categoria do idioma podem divergir. Consulte Templates do WhatsApp para saber como o fluxo de envio resolve isso.
  • Um template de autenticação importado não pode ser duplicado. O Bird não consegue converter o texto gerado pela WhatsApp de volta nas configurações a partir das quais um novo template é criado; isso retorna 422 E15024 WhatsAppTemplateContentNotDuplicable. Em vez disso, crie um novo template com sua própria recomendação de segurança e expiração de código.

Próximos passos