Templates utilitários do WhatsApp
Um template utilitário dá continuidade 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. Use a categoria do slug na lista de templates em vez do nome: bird_signin_alert parece um template de autenticação, mas não é, é utilitário.
Antes de enviar
Escolha um template do catálogo gerenciado ou crie um na sua conta comercial conectada.
Enviar os templates prontos do catálogo do Bird não exige nenhuma verificação da sua parte, assim como autenticação. Criar um template utilitário próprio também não exige: ao contrário de autenticação, a verificação de negócio da Meta nunca se aplica a utilitário, então você pode criar e editar templates utilitários em um espaço de trabalho não verificado. Consulte Verificação de negócio do WhatsApp para saber o que a verificação desbloqueia em outros casos.
to pode ser um número de telefone E.164 ou um ID de usuário com escopo de negócio. Um template utilitário não inclui botão OTP, então não exige o destinatário exclusivamente por número de telefone que autenticação exige.
Todo template utilitário gerenciado do catálogo está registrado apenas em en, com on_missing_language: fail. Solicitar um idioma que o catálogo não oferece falha o envio em vez de recorrer ao inglês ou a qualquer outro idioma.
Enviando um template utilitário
POST /v1/whatsapp/messages com um objeto template nomeando um slug do catálogo:
const msg = await bird.whatsapp.send({
to: "+16505551234",
template: {
slug: "bird_order_confirmation",
language: "en",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "amount", text: "USD 49.99" },
],
},
],
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "amount", "text": "USD 49.99"},
],
}
],
)
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)
}
ref := "A1B2C3D4"
amount := "USD 49.99"
refName := "ref"
amountName := "amount"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: &refName, Text: &ref},
{Type: "text", Name: &amountName, Text: &amount},
},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Components: components,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$components = [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('amount')->setText('USD 49.99'),
]),
];
$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"amount","text":"USD 49.99","type":"text"}],"type":"body"}]' \
--language en \
--template bird_order_confirmation \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"name": "ref",
"text": "A1B2C3D4",
"type": "text"
},
{
"name": "amount",
"text": "USD 49.99",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "bird_order_confirmation"
},
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"template": {
"slug": "bird_order_confirmation",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"name": "ref",
"text": "A1B2C3D4"
},
{
"type": "text",
"name": "amount",
"text": "USD 49.99"
}
]
}
]
}
}'Como em qualquer template gerenciado, omita from: Bird escolhe o número de envio com base na categoria e na região, e defini-lo retorna 422 E15018 WhatsAppSenderNotAllowed. Criar seu próprio template utilitário e enviá-lo funciona da mesma forma que qualquer envio autoral; consulte Enviando com um template para o contrato geral.
Preenchendo as variáveis
Os parâmetros de utilitário são nomeados, o inverso do código posicional único de autenticação. Todo parâmetro carrega um name, e a ordem de um parâmetro nomeado no array não tem significado. Envie uma entrada components para cada bloco que realmente tenha um placeholder; um body sem variáveis não recebe nenhuma entrada components.
Um botão de URL é a única exceção: sua variável é sempre posicional {{1}}, e o envio carrega o valor puro em vez de um endereço completo:
Exemplo de código
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }Para as regras compartilhadas sobre componentes, sub_type, e como os components de um envio correspondem aos placeholders declarados de um template, consulte Enviando com um template e Componentes e parâmetros.
Custo
Um template utilitário entregue dentro de uma janela de atendimento ao cliente aberta pode se qualificar para a tarifa gratuita da Meta. A taxa de envio da Bird é cobrada durante o processamento da mensagem, antes do envio. Um callback posterior de entrega ou leitura determina se uma taxa da Meta se aplica. Considere os dois componentes ao estimar o total.
Consulte Custo e cobrança para saber quando um envio é cobrado, e Preços do WhatsApp para as tarifas.
Pontos de atenção
- A Meta pode recategorizar um template utilitário como marketing por iniciativa própria, e a mensagem continua sendo enviada pelo novo preço, mais alto. Um negócio que a Meta já advertiu por categorização incorreta não recebe nenhum aviso prévio desde abril de 2025; a mudança entra em vigor instantaneamente. Mantenha linguagem promocional, ofertas ou upsells fora do texto de um template utilitário, pois é isso que aciona a mudança. Consulte Diretrizes de templates para saber o que é considerado promocional.
- Um header gif ou um botão copy_code é recusado fora de marketing. Ambos são componentes exclusivos de marketing; declarar qualquer um em um template utilitário falha.
- Um envio autoral não é verificado quanto à quantidade de parâmetros antes de ser cobrado. Envie o número errado de parâmetros em um template próprio e a mensagem é aceita e cobrada, depois rejeitada pela Meta. Envios gerenciados do catálogo não têm essa lacuna.
- Um remetente na WhatsApp Business Account 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
- Templates do WhatsApp: navegação pelo catálogo e o contrato compartilhado de envio por template
- Templates de autenticação: códigos de verificação de uso único e a verificação necessária para criar um
- Templates de marketing: envios promocionais e a conta necessária para criar um
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação