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);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
parameters={"ref": "A1B2C3D4", "amount": "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)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Parameters: map[string]any{"ref": "A1B2C3D4", "amount": "USD 49.99"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
parameters: ['ref' => 'A1B2C3D4', 'amount' => 'USD 49.99'],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--language en \
--parameters '{"amount":"USD 49.99","ref":"A1B2C3D4"}' \
--template bird_order_confirmation \
--to +16505551234curl -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",
"parameters": {
"ref": "A1B2C3D4",
"amount": "USD 49.99"
}
}
}'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:
{ "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
gifou um botãocopy_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
componentsde 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 emcomponentsem um template seu, a mensagem é aceita e cobrada e depois rejeitada pela Meta. Um envioparameterssem 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.
fromprecisa estar na mesma conta que o template. Caso contrário, o envio falha422E15023WhatsAppSenderWABAMismatch.
Próximos passos
- Templates do WhatsApp: como navegar pelo catálogo e o contrato comum de envio por template
- Templates de autenticação: códigos de verificação de uso único e a exigência de verificação para criar um
- Templates de marketing: envios promocionais e a conta de que você precisa para criar um
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.