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);msg = client.whatsapp.send(
to="+14155550100",
template="bird_otp",
language="en",
parameters={"code": "481920"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+14155550100",
Template: "bird_otp",
Language: "en",
Parameters: map[string]any{"code": "481920"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$message = $bird->whatsapp->send(
to: '+14155550100',
template: 'bird_otp',
language: 'en',
parameters: ['code' => '481920'],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--language en \
--parameters '{"code":"481920"}' \
--template bird_otp \
--to +14155550100curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550100",
"template": {
"slug": "bird_otp",
"language": "en",
"parameters": {
"code": "481920"
}
}
}'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 definirfromretorna422E15018WhatsAppSenderNotAllowed. É o contrário de um envio de formato livre, que exigefrom, algo importante se você vem das páginas de mensagens interativas. todeve 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 retorna422E15014WhatsAppRecipientNotSupportedForTemplate.- O código vai em
parameters.code. Ele preenche o placeholder do corpo e o botão de copiar código. Um enviocomponents, por outro lado, recebe exatamente um parâmetro posicional no corpo: o código. Enviar zero parâmetros, ou nomear o parâmetro, retorna422E15003WhatsAppTemplateParameterMismatch. - 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:
{ "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_otpebird_otp_authiflysã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 com422E15063WhatsAppDestinationRestrictedantes 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 com422E15023WhatsAppSenderWABAMismatchantes 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
422E15024WhatsAppTemplateContentNotDuplicable. 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
- Templates do WhatsApp: como navegar pelo catálogo e o contrato comum de envio por template
- Templates de utilidade: atualizações de pedidos, lembretes de agendamento e avisos de conta
- Verificação de empresa do WhatsApp: como a verificação funciona e o que mais ela libera
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.