Variáveis de template do WhatsApp: {{1}} vs nomeados

{
  "type": "BODY",
  "text": "Hi {{1}}! Your order {{2}} ships on {{3}}.",
  "example": { "body_text": [["Layla", "OM-4821", "12 November"]] }
}

{
  "type": "BODY",
  "text": "Hi {{first_name}}! Your order {{order_number}} ships on {{ship_date}}.",
  "example": {
    "body_text_named_params": [
      { "param_name": "first_name", "example": "Layla" },
      { "param_name": "order_number", "example": "OM-4821" },
      { "param_name": "ship_date", "example": "12 November" }
    ]
  }
}

Como envio os parâmetros na chamada de API?

Você envia o nome do template, o idioma e um array components com os valores. Este é o formato para um template posicional:

{
  "messaging_product": "whatsapp",
  "to": "971500000000",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "en" },
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Layla" },
        { "type": "text", "text": "OM-4821" },
        { "type": "text", "text": "12 November" }
      ] }
    ]
  }
}

Em um template nomeado, cada entrada também leva parameter_name, que deve corresponder ao marcador:

{ "type": "text", "parameter_name": "order_number", "text": "OM-4821" }

Como funcionam os parâmetros de mídia no cabeçalho?

Um cabeçalho de mídia não tem variável de texto. Na criação, o cabeçalho guarda um identificador de arquivo de exemplo, obtido no fluxo de upload da Meta, e o exemplo é analisado junto com o template. No envio, você informa o arquivo, por exemplo uma imagem pelo ID de mídia:

{ "type": "header", "parameters": [ { "type": "image", "image": { "id": "1558081531584829" } } ] }

O ID acima é o exemplo da documentação da Meta, não um arquivo real.

Como isso funciona na API da OmniChannels.ai?

Nosso endpoint sendbulk recebe o template como campos de formulário, conforme a documentação da API do WhatsApp:

Exemplo prático: um template de pedido enviado

A "Souq Rafiq" (fictícia), uma varejista dos Emirados Árabes Unidos, quer um aviso de envio com imagem do produto e um botão de rastreamento.

1. Escreva o template de modo que ele não comece nem termine com uma variável: "Hi {{1}}, your order {{2}} has shipped and should arrive on {{3}}. Tap the button to follow it."
2. Adicione o cabeçalho como imagem, o rodapé como texto simples e um botão de URL https://shop.example/track/{{1}} com um exemplo como OM-4821.
3. Envie para análise com exemplos realistas para cada variável e aguarde o status de aprovação.
4. Dispare com os três valores do corpo, o sufixo de rastreamento e, se quiser substituí-la, a imagem do cabeçalho.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-shipped \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_shipped \
  -F templateLanguage=en \
  -F bodyTemplateVariables=Layla \
  -F buttonsTemplateVariable=OM-4821

Este trecho mostra os nomes dos campos para um único valor. Para várias variáveis de corpo por destinatário, use um upload personalizado em vez de repetir o comando. Confirme a codificação com a nossa equipe na primeira campanha.

Como personalizo um template a partir de um CSV?

Use uma linha por destinatário e uma coluna por variável e envie o arquivo em um disparo personalizado.

1. Coloque o número do destinatário no formato internacional na primeira coluna. Veja formato E.164 de número de telefone.
2. Adicione uma coluna por variável e confirme o layout das colunas com a nossa equipe na primeira campanha.
3. Limpe os dados antes: remova espaços, corrija maiúsculas e minúsculas, use um único formato de data e elimine valores vazios, pois uma variável vazia gera uma mensagem quebrada ou um envio com falha.
4. Confira a prévia de várias linhas e envie primeiro para o seu próprio número.

As etapas de limpeza de dados estão em enviar SMS em massa a partir do Excel ou CSV; elas valem igualmente para o WhatsApp.

Como escolho entre posicional e nomeado?

Decida pelo número de pessoas que vão mexer no template e pela quantidade de variáveis.

1. Uma ou duas variáveis, um único responsável: o posicional serve e é o padrão.
2. Três ou mais variáveis, ou várias equipes editando templates: use nomeado, para que cada marcador se explique sozinho.
3. Mesmo texto em vários idiomas: mantenha os mesmos nomes ou números em todas as versões, para que uma única rotina de envio preencha todos os idiomas.
4. Mantenha sempre um registro de qual coluna de origem alimenta cada variável, para que uma edição posterior do template não desloque os dados.

Antes de enviar para análise, leia em voz alta a mensagem final com os valores de exemplo. Se soar artificial, os analistas e os clientes vão achar o mesmo.

Quais são os erros mais comuns?

• Começar ou terminar com uma variável, que a Meta lista como motivo de rejeição.
• Pular números ou repetir o mesmo número fora de ordem em um template posicional.
• Exemplos genéricos como "test", que não dizem nada aos analistas.
• Caracteres especiais como #, $ ou % dentro das variáveis.
• Ordem errada no envio em um template posicional, o que coloca o dado certo no lugar errado.
• parameter_name diferente do marcador em um template nomeado.
• Usar uma variável para esconder a finalidade real da mensagem. Um template cuja categoria não corresponde ao conteúdo pode ser rejeitado ou recategorizado; veja o guia de categorias.
• Limites: este guia relata o que a documentação da Meta afirma no momento da redação. As decisões de análise cabem à Meta e as regras mudam, então confira as páginas linkadas.

Como a OmniChannels.ai ajuda

A BroadNet é uma Meta Business Solution Provider oficial. Na OmniChannels.ai você pode criar templates do WhatsApp com variáveis, mídia e botões, visualizá-los e acompanhar o status de aprovação, e depois enviá-los com valores personalizados pela API ou por um upload de Excel ou CSV em uma campanha. Filtro de duplicados e relatórios de entrega estão incluídos. Veja a página da API do WhatsApp Business e a plataforma de campanhas.