Templates de marketing do WhatsApp

Um template de marketing carrega conteúdo promocional, como uma oferta, anúncio de produto ou cupom. Prepare conteúdo aprovado, permissão do destinatário e uma forma clara de lidar com respostas e cancelamentos de assinatura antes de enviar.

Antes de enviar

O catálogo gerenciado do Bird não inclui nenhum template de marketing, então um envio de marketing sempre usa um template criado pelo seu espaço de trabalho, em uma WhatsApp Business Account própria:

Conecte uma WhatsApp Business Account e um número próprio. Consulte Configuração de número de telefone.
Crie um template com a categoria marketing e envie para revisão. Veja Diretrizes de templates para saber o que é aprovado.
Envie a partir de um número na mesma WhatsApp Business Account do template. from é obrigatório em um envio de marketing, e um remetente em uma conta diferente é recusado 422 E15023 WhatsAppSenderWABAMismatch antes de qualquer cobrança.

Enviando um template de marketing

POST /v1/whatsapp/messages com from definido e um objeto template informando seu próprio slug:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13125550101",
  template: {
    slug: "summer_sale",
    language: "en",
    components: [
      {
        type: "header",
        parameters: [{ type: "image", url: "https://cdn.example.com/banners/summer.png" }],
      },
      { type: "body", parameters: [{ type: "text", name: "first_name", text: "Pablo" }] },
      { type: "button", parameters: [{ type: "text", text: "SUMMER25" }] },
    ],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13125550101",
    template="summer_sale",
    language="en",
    components=[
        {
            "type": "header",
            "parameters": [{"type": "image", "url": "https://cdn.example.com/banners/summer.png"}],
        },
        {"type": "body", "parameters": [{"type": "text", "name": "first_name", "text": "Pablo"}]},
        {"type": "button", "parameters": [{"type": "text", "text": "SUMMER25"}]},
    ],
)
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)
	}
	name := "Pablo"
	nameKey := "first_name"
	banner := "https://cdn.example.com/banners/summer.png"
	coupon := "SUMMER25"
	components := []bird.WhatsAppMessageTemplateComponent{
		{Type: "header", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "image", Url: &banner}}},
		{Type: "body", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Name: &nameKey, Text: &name}}},
		{Type: "button", Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &coupon}}},
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+16505551234",
		From:     "+13125550101",
		Template: "summer_sale",
		Language: "en",
		Components: components,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$components = [
    (new WhatsAppMessageTemplateComponent())
        ->setType('header')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('image')->setUrl('https://cdn.example.com/banners/summer.png'),
        ]),
    (new WhatsAppMessageTemplateComponent())
        ->setType('body')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('first_name')->setText('Pablo'),
        ]),
    (new WhatsAppMessageTemplateComponent())
        ->setType('button')
        ->setParameters([
            (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('SUMMER25'),
        ]),
];
$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13125550101',
    template: 'summer_sale',
    language: 'en',
    components: $components,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13125550101 \
  --components '[{"parameters":[{"type":"image","url":"https://cdn.example.com/banners/summer.png"}],"type":"header"},{"parameters":[{"name":"first_name","text":"Pablo","type":"text"}],"type":"body"},{"parameters":[{"text":"SUMMER25","type":"text"}],"type":"button"}]' \
  --language en \
  --template summer_sale \
  --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",
      "from": "+13125550101",
      "template": {
        "slug": "summer_sale",
        "language": "en",
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "image",
                "url": "https://cdn.example.com/banners/summer.png"
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "name": "first_name",
                "text": "Pablo"
              }
            ]
          },
          {
            "type": "button",
            "parameters": [
              {
                "type": "text",
                "text": "SUMMER25"
              }
            ]
          }
        ]
      }
    }'

Os parâmetros do corpo são nomeados, assim como em utility. Cada parâmetro carrega um name, e a ordem no array não tem significado.
O código de um botão de cupom é um parâmetro text comum, como o do botão acima. Não existe um tipo de parâmetro separado para código de cupom.
Um header gif recebe um parâmetro gif, não video ou image. Marketing é a única categoria que aceita um header de GIF animado.
Os valores de um carrossel vão em cards, não em parameters, e o envio precisa fornecer exatamente o número de cards com que o template foi aprovado.

Bird direciona automaticamente todo envio de marketing para o Marketing Messages API da Meta; você não precisa ativar nada e não há opção por envio. O status de onboarding da conta comercial nesse API controla as otimizações da Meta, não a entrega em si, com uma exceção: um header gif exige uma conta com onboarding concluído ou o envio falha em WhatsApp. Veja Templates de marketing para o estado da conta, o que o onboarding desbloqueia e onde o marketing é limitado por país.

Descadastramento

Quando Bird recebe um evento válido de parada de marketing da Meta, registra uma preferência de destinatário para aquela conta comercial. Essa preferência é separada de uma supressão de todas as mensagens. Verifique ambos os registros antes de enviar. Uma falha de entrega pode chegar antes do evento de preferência correspondente; preserve a escolha do destinatário e investigue esse histórico em vez de tentar novamente. Consulte Preferências para registrar e ler esses registros.

Custo

Use a tarifa de marketing publicada para o destino e a moeda. Bird cobra sua taxa de envio antes da submissão; um resultado faturável de entrega ou leitura pode adicionar a taxa da Meta. Consulte Custo e cobrança e Preços WhatsApp.

Pontos de atenção

A Meta recategoriza para marketing, nunca para fora, e isso muda o preço. Um template que a Meta considerar promocional na essência se torna marketing independentemente da categoria que você enviou, e o envio continua saindo pelo novo preço, mais alto. Não há como recusar nem editar a categoria de volta; a solução é criar um novo template.
131049 é uma pausa de entrega, não um limite de requisições que você configurou, e tentar novamente piora a situação. A Meta reporta 131049 tanto para a pausa geral nos EUA quanto para um limite de marketing por usuário, e a própria orientação dela é esperar aproximadamente um dia antes de reenviar. Reenviar antes pode tornar a conta indisponível para aquele destinatário por mais tempo e distorce sua própria taxa de entrega. Bird reporta a falha como rate_limited.
131050 significa que o destinatário desativou "Offers and announcements", e o envio nunca deve ser repetido. A Meta aceita o envio e depois recusa a entrega. A resposta correta é o caminho de preferências de mensagens, não um reenvio: suprima o destinatário você mesmo ou aguarde até que ele reative a entrega, o que Bird descobre pelo mesmo mecanismo de preferência que reportou a parada. Consulte Preferências.
132015 e 132016 são pausas de template, não um problema do destinatário. 132015 é uma pausa por baixa qualidade; 132016 é a desativação permanente após pausas repetidas, e a única solução é um novo template com conteúdo diferente. Verifique o status do idioma em vez do template, já que um idioma pausado interrompe o envio imediatamente.
Um remetente na WhatsApp Business Account errada é recusado antes de qualquer cobrança. from precisa estar na mesma conta que o template, ou 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 marketing: o Marketing Messages API, status de onboarding e onde o marketing é limitado
Preferências: registro e leitura de declarações de destinatários
Templates de utility: atualizações de pedidos, lembretes de compromissos e avisos de conta

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

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