# 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](/docs/knowledge-base/whatsapp/business-verification) 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:

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/templates/utility.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/templates/utility.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/templates/utility.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/templates/utility.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/templates/utility.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/templates/utility.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/templates/utility.curl.md)

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`](/docs/api/errors/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](/docs/guides/whatsapp/templates#sending-with-a-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:

```json
{ "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](/docs/guides/whatsapp/templates#sending-with-a-template) e [Componentes e parâmetros](/docs/guides/whatsapp/sending-whatsapp#components-and-parameters).

## 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](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing) para saber quando um envio é cobrado, e [Preços do WhatsApp](/products/whatsapp/pricing) 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](/docs/knowledge-base/whatsapp/template-guidelines) 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`](/docs/api/errors/E15023) `WhatsAppSenderWABAMismatch`.

## Próximos passos

- [Templates do WhatsApp](/docs/guides/whatsapp/templates): navegação pelo catálogo e o contrato compartilhado de envio por template
- [Templates de autenticação](/docs/guides/whatsapp/templates/authentication): códigos de verificação de uso único e a verificação necessária para criar um
- [Templates de marketing](/docs/guides/whatsapp/templates/marketing): envios promocionais e a conta necessária para criar um

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)