Templates do WhatsApp

Envios do WhatsApp iniciados pela empresa usam um template pré-aprovado. Um template contém texto fixo e variáveis, então o envio fornece apenas valores como um código OTP ou um número de pedido.

O Bird oferece um catálogo gerenciado, registra o conteúdo dele no WhatsApp e o envia pelos números do próprio Bird; os slugs desse catálogo começam com bird_. Um espaço de trabalho que conectou um número próprio também pode criar templates na própria conta WhatsApp Business. A página Approved templates mostra todos os templates que o espaço de trabalho pode enviar e como cada um é exibido.

Como navegar pelos templates no painel

Abra Approved templates em WhatsApp > Approved templates. Your templates reúne os templates criados por este espaço de trabalho; All templates inclui também o catálogo gerenciado pelo Bird. Pesquise pelo nome ou filtre por status e categoria, e alterne entre a grade de cartões e a visualização em lista com o seletor ao lado dos filtros.

Na visualização em lista, cada linha mostra os campos de que você precisa para escolher e enviar um template:

Status: indica se o template pode ser enviado de modo geral. Os templates do catálogo gerenciado informam active; um template próprio informa a situação da própria aprovação. Confira a lista de idiomas para confirmar que o idioma necessário está disponível.
Name: o rótulo de exibição, com o slug do template logo abaixo. Envie usando o slug.
Languages: os idiomas em que o template está registrado, como inglês e holandês.
Category: authentication, utility ou marketing. A categoria define como a WhatsApp trata a mensagem, de qual número Bird um template gerenciado é enviado e, junto com o país de destino, o preço.
WABA: Bird-managed para templates do catálogo. Um template próprio mostra a WhatsApp Business Account que o contém e só é enviado de um número dessa mesma conta.
Updated: quando o template foi alterado pela última vez.

Clique em uma linha para abrir os detalhes do template.

O que um template contém

A visualização de detalhes exibe o corpo da mensagem, as variáveis e os botões em uma prévia no estilo do WhatsApp.

Os detalhes também trazem um exemplo em cURL para POST /v1/whatsapp/messages, com o host regional e os valores de exemplo do template. Substitua a chave de API, o destinatário e os valores das variáveis antes de enviar.

O exemplo é a forma mais rápida de ver a estrutura que um envio precisa seguir. Pela API, o mesmo conteúdo vem da versão do template (Como ler o conteúdo de um template).

Como listar templates pela API

GET /v1/whatsapp/templates retorna um catálogo com paginação por cursor. A solicitação exige acesso de leitura a whatsapp_management. Use HTTP ou um método de solicitação bruta do SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

templates = client.get("/v1/whatsapp/templates")

var out struct {
	Data []struct {
		Slug   string `json:"slug"`
		Status string `json:"status"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
	log.Fatal(err)
}

$templates = $bird->get('/v1/whatsapp/templates');

curl https://us1.platform.bird.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $BIRD_API_KEY"

Cada entrada identifica o template, a categoria e os idiomas disponíveis. Para obter o conteúdo da mensagem, leia a versão ativa separadamente.

Exemplo de código

{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}

A resposta de exemplo abrevia as listas de idiomas de bird_otp.

Os campos dos quais um envio depende:

slug: o identificador usado em um envio. Os slugs de templates gerenciados começam com bird_, um prefixo reservado a eles.
waba: a WhatsApp Business Account que mantém os idiomas do template na Meta e à qual o número remetente precisa pertencer. Fica ausente em um template gerenciado, porque a Bird gerencia a conta dele.
available_languages: os idiomas que podem ser enviados. Um idioma pausado, desativado, arquivado ou limitado sai desta lista.
on_missing_language: o que acontece quando o idioma solicitado não está disponível. Os templates WhatsApp gerenciados pela Bird usam fail, que rejeita o envio em vez de substituir por outro idioma.

Status e status do idioma

Os templates gerenciados pela Bird informam status: active. languages.<tag>.status informa o estado de um idioma na WhatsApp, como approved, paused ou disabled.

Um template ativo ainda pode ter um idioma indisponível. Use available_languages para decidir se um idioma pode ser enviado.

Como ler o conteúdo de um template

O conteúdo da mensagem pertence a um idioma da versão ativa. Leia live_version_id no template e depois solicite o idioma necessário:

const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});

language = client.get(
    "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)

var language map[string]any
if err := client.Get(context.Background(),
	"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
	&language); err != nil {
	log.Fatal(err)
}

$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');

curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
  -H "Authorization: Bearer $BIRD_API_KEY"

A referência ao template aceita um ID slug ou wat_. GET …/versions/{version_id}/languages lista os idiomas da versão sem o conteúdo deles.

Exemplo de código

{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}

Um envio preenche esses placeholders pelo nome. example_parameters identifica cada um. Neste exemplo, o parameters do envio recebe as chaves ref e amount. Em um template posicional, as chaves são os números dele, como 1, com duas exceções: o código de um template de autenticação usa a chave code, e o sufixo numerado de um botão de url usa button_url. Botões com parâmetros têm seu próprio example_parameters.

A category do idioma é a categoria da Meta usada para definir o preço. Ela pode ser diferente da categoria registrada do template se a Meta reclassificar o idioma.

A lista variables da versão resume cada placeholder com sua chave, seu tipo, o indicador de obrigatoriedade e sua restrição. Placeholders nomeados usam o próprio nome como chave. Placeholders posicionais usam seu número, exceto o código de autenticação (code) e o sufixo de um botão de url (button_url). O parameters de um envio recebe essas chaves.

Enviar com um template

Indique o template no objeto template do envio e preencha as variáveis por meio de parameters. O payload completo está em Enviar mensagens do WhatsApp:

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --to +15551234567

curl -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" }
    }
  }'

Envio por categoria

Todo template tem uma das três categorias da Meta. A categoria determina o que você precisa fazer para que um envio funcione e quanto ele custa. Criar ou copiar um template de autenticação próprio exige uma empresa verificada, mas enviá-lo não exige: o bird_otp gerenciado da Bird fica na própria WhatsApp Business Account da Bird e é enviado sem nenhuma verificação da sua parte. Templates de marketing sempre são enviados de uma WhatsApp Business Account própria, por uma segunda API da Meta para a qual a Bird direciona automaticamente. Templates utilitários são os que têm menos pré-requisitos entre os três.

Templates de autenticação: códigos de verificação de uso único, o botão de copiar código e a exigência de verificação para criar um template
Templates utilitários: atualizações de pedidos, lembretes de agendamento e avisos de conta
Templates de marketing: envios promocionais, a conta comercial necessária e a expectativa de opção de descadastro

Próximos passos

Enviar mensagens do WhatsApp: o payload de envio completo em que o objeto template se encaixa
Diretrizes de templates do WhatsApp: as regras com base nas quais a Meta analisa um template
Templates de autenticação: códigos de verificação de uso único e a exigência de verificação da empresa para criar um
Preços do WhatsApp: como a categoria e o destino definem o preço

Continue com a documentação, guias e exemplos sobre este tópico.

Experimente na prática e obtenha um resumo de implementação

Recursos relacionados