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

WhatsApp Business API para ofertas promocionais

O cenário envia um modelo de marketing personalizado pelo WhatsApp para contatos que optaram por receber quando uma campanha promocional começa.

Visão geral do caso de uso

O cenário envia um modelo de marketing personalizado pelo WhatsApp para contatos que optaram por receber mensagens quando uma campanha promocional começa. A mensagem inclui o nome do cliente, o produto ou categoria promovida, detalhes da oferta e a data de término da promoção. Um botão de URL estático abre a página de destino da oferta.

Exemplo de modelo

Olá {{1}}! Temos uma oferta especial em {{2}}: <c2>{{3}}</c2}. A promoção é válida até {{4}}. Clique no botão abaixo para ver a oferta!

Ver oferta
  • {{1}}
    nome do cliente
  • {{2}}
    nome do produto ou categoria promovida
  • {{3}}
    detalhes da oferta promocional (valor do desconto, condições)
  • {{4}}
    oferta válida até a data
  • “Ver oferta”
    botão — fixado no template da Meta
WhatsApp Business API for promotional offer broadcast

Quando usá-lo

Utilize este cenário quando você já tiver uma lista de marketing no WhatsApp com opt-in e quiser anunciar um desconto ou oferta especial para essa base — não para contatos frios. É adequado para vendas sazonais de varejo e e-commerce, promoções de upgrade de SaaS para assinantes existentes e agências que realizam transmissões promocionais para marcas de clientes a partir de segmentos de CRM.

Alcançar contatos que optaram por receber mensagens fora da janela de 24 horas
Um modelo de MARKETING aprovado entrega a oferta promocional pelo WhatsApp mesmo quando nenhuma conversa está aberta, de modo que a campanha não dependa de uma mensagem recebida recentemente.
Ofertas que nomeiam o cliente e o negócio
Quatro variáveis de corpo carregam o nome de contato, produto ou categoria promovida, detalhes da oferta e data de expiração, assim a transmissão é lida como uma promoção direcionada em vez de um disparo genérico.
Um toque na página de promoção
Um botão de URL estático fixo no template Meta abre a página de aterrissagem da oferta, para que o contato possa agir sobre o desconto sem esperar dentro da janela de resposta.
Menos montagem manual de campanhas
CRM ou automação de marketing fornece os campos de segmentação e personalização, e o template é enviado com esse gatilho — nenhum representante reconstrói a lista ou reescreve os termos da oferta para cada contato.
Rastreamento da entrega da campanha
Os resultados de entrega são registrados para o rastreamento de desempenho da campanha, para que o marketing saiba quantos contatos que optaram por participar receberam a oferta antes de medir as conversões em outros lugares.

Fluxo de Trabalho

  1. Desencadear

    O marketing ou o CRM seleciona um segmento que optou por participar para a campanha promocional.

    event · triggered

  2. Capturar evento

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

    phone: "+…"

  3. Construa e envie

    Um modelo promocional personalizado é criado com quatro variáveis e um botão de URL estático.

    POST /sendTemplate

  4. Entregue

    Cada contato que optou por receber informações recebe a mensagem da oferta de marketing do WhatsApp.

    delivered

  5. Status rastreado

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

    status: "read"

WhatsApp Business API for promotional offer broadcast

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave da API
  2. Conta do WhatsApp Business · Como conectar WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo do 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_PRODUCTORSERVICENAME="___"         # {{2}} product or service name
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_PRODUCTORSERVICENAME=$TEST_PRODUCTORSERVICENAME" \
            "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}} product or service name → ${TEST_PRODUCTORSERVICENAME}
# {{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_PRODUCTORSERVICENAME}" },
        { "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": true significam que 1MSG aceitou a mensagem para envio — não que ela já tenha chegado ao telefone do cliente. Salve o campo id (parece com wamid.…) para correlacionar os callbacks de entrega.

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

    Aceito para envio — não ainda no telefone do cliente

  • id

    Armazene-o; os retornos de chamada de entrega e hookInfo são vinculados a isso.

A entrega em si chega depois, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG POSTa atualizações de status para seu endpoint HTTPS em um payload de nível superior hooks[].

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

    enviado, entregue, lido — ou um status de falha quando aplicável

  • id

    Correla o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber chamadas de retorno, consulte 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 aguardando por isso.

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 pela Meta.

Relacionado

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 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.
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.
Campanhas de Marketing
WhatsApp Business API para reengajar leads interessados
O cenário envia um modelo personalizado de WhatsApp para um lead ou cliente que demonstrou interesse anteriormente, mas ficou inativo.
Campanhas de Marketing
WhatsApp Business API para mensagem de boas-vindas
O cenário envia um modelo personalizado WhatsApp quando um usuário conclui o cadastro.

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