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

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.

Visão geral do caso de uso

O cenário envia um modelo de WhatsApp personalizado quando o marketing lança uma campanha visual. A mensagem inclui o nome do contato, o nome da campanha e um breve texto criativo. Um botão de URL estático abre a página de destino da campanha onde a arte do banner está localizada.

Exemplo de template

Olá, {{1}}! Nossa campanha "{{2}}" está agora ativa. {{3}} Toque no botão abaixo para abrir a página da campanha e explorar a oferta.

Visualizar campanha
  • {{1}}
    nome do cliente
  • {{2}}
    nome da campanha
  • {{3}}
    gancho criativo ou slogan para a campanha
  • “Visualizar campanha”
    button — fixed in the Meta template
WhatsApp Business API for promo banner broadcast

Quando usar isso

Use este cenário quando o marketing enviar uma criação visual com uma landing page dedicada e precisar que toda a base opt-in veja o nome da campanha e clique — não uma linha de desconto simples ou uma lista de produtos. Ele se encaixa em impulsos sazonais de varejo, ondas de lançamento de marca e agências que estão conduzindo campanhas criativas nomeadas para marcas de clientes no WhatsApp.

Alcance da campanha sem um chat aberto
Um modelo de MARKETING aprovado atinge contatos opt-in fora da janela de 24 horas, então a transmissão não depende de uma conversa existente.
A parte criativa está na página inicial.
O corpo nomeia a campanha e uma frase de impacto curta, enquanto um botão de URL estático abre a página de destino do banner — nenhuma variável de cabeçalho de imagem é necessária na carga da API.
Personalização em escala de transmissão
Três variáveis de corpo carregam o nome do contato, o título da campanha e o slogan criativo, para que cada mensagem seja lida como um convite de campanha nomeado, em vez de um envio genérico.
Menos trabalho manual de listagem
O CRM ou a automação carrega o segmento no dia do lançamento e o modelo é enviado a partir desse gatilho, assim o marketing não precisa reescrever o texto da campanha para cada contato.
Campanhas mensuráveis de toques
Os resultados da entrega retornam para o sistema de envio e os toques no botão levam para a URL da campanha, então os relatórios de desempenho se conectam à mesma transmissão realizada.

Fluxo de Trabalho

  1. Acionar

    O marketing agenda o lançamento de uma campanha e define o segmento de contato.

    event · triggered

  2. Registrar evento

    O sistema resolve cada telefone de destinatário e os campos de personalização da campanha.

    phone: "+…"

  3. Construa e envie

    Um modelo de campanha personalizado é construído com três variáveis de corpo e um botão de URL estático.

    POST /sendTemplate

  4. Entregue

    Cada contato recebe a mensagem da campanha do WhatsApp.

    delivered

  5. Status monitorado

    As entregas e os toques nos botões são registrados para o desempenho da campanha.

    status: "read"

WhatsApp Business API for promo banner broadcast

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo 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_ADDITIONALINFO="___"         # {{3}} additional info

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_ADDITIONALINFO=$TEST_ADDITIONALINFO"; 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}} additional info → ${TEST_ADDITIONALINFO}
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_ADDITIONALINFO}" }
      ]
    }

  ]
}
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á chegou ao telefone do cliente. Salve o campo id (parece com wamid.…) para correlacionar os callbacks de entrega.

200 OKResposta
{
  "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 entrega e hookInfo são vinculados a isso

A entrega em si chega mais tarde, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG envia 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ê prefere não receber chamadas de retorno, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega costuma ser 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 frio requerem um template 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 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.
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