Sign inGet Started

Templates de utilidade do WhatsApp

Um template de utilidade dá seguimento a algo que o destinatário já fez: um pedido, um pagamento, uma reserva, um login. O catálogo do Bird oferece oito deles, incluindo bird_signin_alert e bird_delivery_update. Confira a categoria de um slug na lista de templates, não pelo nome: bird_signin_alert parece um template de autenticação, mas não é; é de utilidade.

Antes de enviar

Escolha um template gerenciado do catálogo ou crie um template de utilidade na sua conta comercial conectada.

Para enviar os templates do catálogo do Bird, você não precisa de nenhuma verificação, assim como na autenticação. Para criar seu próprio template de utilidade, também não: diferentemente da autenticação, a exigência de verificação comercial da Meta nunca se aplica à categoria de utilidade. Assim, você pode criar e editar templates de utilidade em um espaço de trabalho não verificado. Consulte Verificação comercial do WhatsApp para saber o que a verificação libera em outros casos.

to pode ser um número de telefone E.164 ou um ID de usuário com escopo da empresa. Um template de utilidade não tem botão OTP, então não exige um destinatário identificado apenas por número de telefone, como a autenticação exige.

Todo template de utilidade gerenciado do catálogo está registrado apenas em en, com on_missing_language: fail. Se você solicitar um idioma que o catálogo não oferece, o envio falha, sem recorrer ao inglês nem a outro idioma.

Como enviar um template de utilidade

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

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  template: {
    slug: "bird_order_confirmation",
    language: "en",
    parameters: { ref: "A1B2C3D4", amount: "USD 49.99" },
  },
});
console.log(msg.id, msg.status);

Como em qualquer template gerenciado, omita from: o Bird escolhe o número de envio a partir da categoria e da região, e, se você definir esse campo, a resposta será 422 E15018 WhatsAppSenderNotAllowed. Criar e enviar seu próprio template de utilidade funciona da mesma forma que qualquer envio de template criado por você; consulte Envio com um template para conhecer o contrato geral.

Preenchimento das variáveis

As variáveis de utilidade são nomeadas, então cada uma tem sua própria chave em parameters, como ref e amount. Um botão de URL com sufixo numerado {{1}} usa a chave button_url. Um sufixo nomeado usa o próprio nome. O envio leva apenas o valor, não o endereço completo:

Exemplo de código
{ "parameters": { "ref": "A1B2C3D4", "button_url": "A-4192" } }

Um envio components, por outro lado, nomeia cada parâmetro do corpo, e a ordem de um parâmetro nomeado no array não tem significado. Para as regras comuns sobre componentes, sub_type e sobre como os components de um envio correspondem aos placeholders declarados no template, consulte Envio com um template e Componentes e parâmetros.

Custo

Um template de utilidade entregue dentro de uma janela de atendimento ao cliente aberta recebe a tarifa gratuita da Meta até 30 de setembro de 2026. A partir de 1º de outubro de 2026, a Meta cobra por ele como por qualquer outro template de utilidade (mudanças de preço de outubro de 2026). A tarifa de saída da Bird é cobrada durante o processamento da mensagem, antes do envio à Meta. Um callback posterior de entrega ou leitura determina se a tarifa da Meta se aplica. Considere os dois componentes ao estimar o total.

Consulte Custo e faturamento para saber quando um envio é cobrado e Preços do WhatsApp para as tarifas.

Pontos de atenção

  • A Meta pode recategorizar um template de utilidade como marketing por iniciativa própria, e a mensagem continua sendo enviada pelo novo preço, mais alto. Desde abril de 2025, uma empresa que a Meta já advertiu por categorização incorreta não recebe nenhum aviso prévio, e a mudança vale imediatamente. Não inclua linguagem promocional, ofertas ou upsells no texto de um template de utilidade, porque é isso que provoca a mudança. Consulte Diretrizes de templates para saber o que é considerado promocional.
  • Um cabeçalho gif ou um botão copy_code é recusado fora de marketing. Ambos são componentes exclusivos de marketing, e declarar qualquer um deles em um template de utilidade gera falha.
  • Um envio components de template próprio não tem a quantidade de parâmetros verificada antes da cobrança. Se você enviar um número errado de parâmetros em components em um template seu, a mensagem é aceita e cobrada e depois rejeitada pela Meta. Um envio parameters sem uma chave obrigatória é recusado antes de qualquer cobrança, e os envios do catálogo gerenciado não têm essa falha.
  • Um remetente na conta comercial do WhatsApp errada é recusado antes de qualquer cobrança. from precisa estar na mesma conta que o template. Caso contrário, o envio falha 422 E15023 WhatsAppSenderWABAMismatch.

Próximos passos