💬 Shared Inbox do WhatsApp na nova PlataformaMais
1msg official logo

WhatsApp Business API para transmissão de campanha sazonal

O cenário envia um template de marketing personalizado pelo WhatsApp quando uma campanha sazonal baseada em calendário é ativada.

Visão geral do caso de uso

O cenário envia um modelo de marketing personalizado pelo WhatsApp quando uma campanha sazonal dirigida pelo calendário é ativada. A mensagem inclui o nome do cliente, o nome da estação ou ocasião, detalhes da oferta sazonal e a data de término da campanha. Um botão de URL estático abre a página de destino da coleção ou venda sazonal.

Exemplo de modelo

Olá{{1}}! Nossa{{2}}campanha está no ar:{{3}}. A promoção de temporada vai até{{4}}. Toque o botão abaixo para explorar a coleção e comprar agora.

Compre na liquidação de temporada
  • {{1}}
    nome do cliente
  • {{2}}
    estação ou ocasião do calendário (Black Friday, Ano Novo, volta às aulas, promoção de verão)
  • {{3}}
    detalhes da oferta sazonal (tema de desconto, categorias em destaque ou foco em presentes)
  • {{4}}
    campanha válida até a data
  • “Compre na liquidação de temporada”
    botão — fixo no modelo Meta
WhatsApp Business API for seasonal campaign broadcast

Quando usá-lo

Use este cenário quando uma temporada do calendário ou feriado for a principal razão para comprar — Black Friday, guias de presentes de Ano Novo, volta às aulas ou uma liquidação de verão com uma janela de campanha fixa — e você já tiver uma lista de WhatsApp opt-in. Isso se encaixa em impulsos sazonais de varejo, ondas de matrícula educacional e agências que realizam campanhas de feriados nomeadas para marcas de clientes de segmentos de CRM. Não é para um desconto genérico sem um gancho sazonal, uma push de banner apenas criativa, ou um lembrete de que uma oferta não relacionada está prestes a acabar.

Momentos de compra do calendário de passeios no WhatsApp
Um template de MARKETING aprovado alcança contatos opt-in fora da janela de 24 horas, assim a ocasião sazonal em si pode acionar a transmissão sem esperar por uma mensagem de entrada.
Campanhas que nomeiam a estação e a janela
Quatro variáveis de corpo carregam o nome do contato, o título da ocasião, os detalhes da oferta sazonal e a data de término da campanha, para que a mensagem seja lida como um evento sazonal com prazo definido em vez de uma promoção genérica.
Um toque na coleção sazonal
Um botão de URL estático fixo no template Meta abre a página de destino sazonal, para que os contatos possam comprar a coleção da campanha sem depender de respostas em texto livre.
Menos trabalho manual com listas sazonais
O CRM ou a automação carregam o segmento de opt-in quando a janela da campanha se abre e o template é enviado com esse gatilho, para que o marketing não precise reescrever o texto do evento para cada contato.
Entrega de campanha sazonal mensurável
Os resultados de entrega retornam ao sistema de envio e são registrados contra a mesma execução de transmissão, de modo que os relatórios de campanhas sazonais estão ligados ao período do calendário que os iniciou.

Fluxo de Trabalho

  1. Desencadear

    O marketing planeja uma campanha sazonal com um calendário definido e um segmento de contatos.

    event · triggered

  2. Evento de captura

    O sistema resolve números de telefone e campos de personalização sazonais para cada contato.

    phone: "+…"

  3. Construir e enviar

    Um modelo sazonal personalizado é construído com quatro variáveis e um botão URL estático.

    POST /sendTemplate

  4. Entregue

    Cada contato que optou por receber informações recebe a mensagem da campanha sazonal via WhatsApp.

    delivered

  5. Status em acompanhamento

    Os resultados de entrega são registrados para o acompanhamento do desempenho da campanha sazonal.

    status: "read"

WhatsApp Business API for seasonal campaign broadcast

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como conseguir a chave da API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo de WhatsApp · Como Aprovar o Template WABA
  4. Consentimento do cliente · Como Gerenciar o Consentimento dos Clientes

Exemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CUSTOMERNAME="___"         # {{1}} customer name
TEST_TOPIC="___"         # {{2}} topic or subject
TEST_DETAILS="___"         # {{3}} change details
TEST_DATE="___"         # {{4}} date or time

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_TOPIC=$TEST_TOPIC" \
            "TEST_DETAILS=$TEST_DETAILS" \
            "TEST_DATE=$TEST_DATE"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} topic or subject → ${TEST_TOPIC}
# {{3}} change details → ${TEST_DETAILS}
# {{4}} date or time → ${TEST_DATE}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_TOPIC}" },
        { "type": "text", "text": "${TEST_DETAILS}" },
        { "type": "text", "text": "${TEST_DATE}" }
      ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to client."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Status de resposta e entrega

HTTP 2xx e JSON"sent": truemean 1MSGaceitaa mensagem para envio — não que já tenha chegado ao telefone do cliente.idcampowamid.…) para correlacionar os retornos de entrega.

200 OKResposta
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Aprovado para envio.nãoainda no telefone do cliente

  • id

    Armazene isso; chamadas de entrega.hookInfoestão focados nisso

A entrega em si chega mais tarde, como um retorno separado. Registre um webhookPOST …/webhook) e 1MSG envia atualizações de status para o seu endpoint HTTPS em um nível superiorhooks[]carga.

200 OKWebhook de status de entrega — payload recebido
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    sent, delivered, read— ou um status de falha quando aplicável

  • id

    Correla o retorno de chamada com oidretornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você prefere não receber retornos de chamada, escolha não participar.GET {base}/{channel}/hookInfo?messageId=<id>em vez disso. Na prática, a entrega geralmente é concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando por ela.

Erros comuns

StatusRespostaCausa
200Message was not sent: template is not definednamespace, template or language missing from the request body.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.
403access deniedThe token is wrong, or belongs to a different channel than the URL.
429too many requests. please try laterThe channel is over its send rate.

Perguntas Frequentes

Sim — mensagens de WhatsApp de início a frio requerem um modelo aprovado pelo Meta.

Relacionado

Campanhas de Marketing
WhatsApp Business API para engajamento de conteúdo
O cenário envia um template de marketing pelo WhatsApp quando a empresa publica conteúdo educacional ou de entretenimento para contatos optados.
Campanhas de Marketing
WhatsApp Business API para notícias da empresa
O cenário envia um modelo de WhatsApp personalizado quando a empresa publica notícias sobre a empresa ou serviços.
Campanhas de Marketing
WhatsApp Business API para acompanhamento pós-compra
O cenário envia um modelo de marketing pelo WhatsApp após uma compra, quando uma oferta de acompanhamento é relevante — reabastecimento ou produto complementar.
Campanhas de Marketing
WhatsApp Business API para reativação de clientes inativos
O cenário envia um modelo de marketing personalizado pelo WhatsApp para um cliente existente que comprou ou usou o serviço antes, mas está inativo há meses.
Campanhas de Marketing
WhatsApp Business API para envio de convites para eventos
O cenário envia um template de marketing para WhatsApp personalizado para contatos que optaram por receber informações sobre um evento público futuro.
Campanhas de Marketing
WhatsApp Business API para catálogo de produtos e serviços
O cenário envia um modelo de marketing personalizado pelo WhatsApp para contatos que optaram por receber, quando a empresa atualiza seu catálogo completo.
Campanhas de Marketing
WhatsApp Business API para transmissão de novidades
O cenário envia um modelo personalizado de WhatsApp quando novos itens ou uma coleção aparecem no catálogo.
Campanhas de Marketing
WhatsApp Business API para envio de banner promocional
O cenário envia um modelo de WhatsApp personalizado quando o marketing lança uma campanha visual.

Crie para o WhatsApp em horas
sem complicações de infraestrutura