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

WhatsApp Business API para mensagem de boas-vindas

O cenário envia um modelo personalizado WhatsApp quando um usuário conclui o cadastro.

Visão geral do caso de uso

O cenário envia um modelo de WhatsApp personalizado quando um usuário conclui o registro. A mensagem inclui o nome do cliente e o serviço ou aplicativo para o qual ele se inscreveu. Um botão de URL estático abre a página da conta ou a página de início.

Exemplo de modelo

Bem-vindo {{1}}! Obrigado por se registrar no {{2}}. Estamos empolgados em tê-lo a bordo. Toque no botão abaixo para abrir sua conta e completar seus primeiros passos. Se precisar de ajuda para começar, fique à vontade para responder a esta mensagem.

Abrir Conta
  • {{1}}
    nome do cliente
  • {{2}}
    nome do serviço ou aplicativo para o qual o usuário se registrou
  • “Abrir Conta”
    botão — fixo no template Meta
WhatsApp Business API for registration welcome message

Quando usá-lo

Use este cenário quando um usuário finalizar o registro com um número de telefone cadastrado e o negócio precisar de uma recepção calorosa que chegue imediatamente — antes que eles se afastem do processo de integração. Isso se aplica a SaaS e aplicativos móveis recebendo novos cadastrados, portais e marketplaces incentivando a conclusão de perfis, e agências conectando webhooks de registro de clientes ao onboard automatizado via WhatsApp.

Bem-vindo! Aproveite seu interesse para se inscrever.
O app emite um evento de registro-completo com o telefone coletado durante a inscrição, e um modelo aprovado chega ao novo usuário no WhatsApp, mesmo que nenhuma conversa esteja aberta ainda.
Saudações, [nome]! Parabéns pelo seu aplicativo!
Duas variáveis do corpo carregam o nome do cliente e o serviço ou aplicativo para o qual se registrou, de modo que a saudação lê-se como uma confirmação pessoal em vez de uma transmissão genérica.
Um toque na conta
Um botão de URL estático fixo no template Meta abre a página da conta ou a página de início, para que o usuário tenha um caminho direto sem esperar dentro da janela de resposta de 24 horas.
Sem trabalho manual de boas-vindas
O sistema extrai o nome e o contexto do serviço do payload de registro e envia o template automaticamente, para que ninguém precise digitar os detalhes novamente ou lembrar de enviar uma mensagem a cada novo usuário.
Rastreamento de entrega de onboarding
O resultado da entrega é registrado para análises de integração ou acompanhamento de suporte, para que a equipe saiba se a mensagem de boas-vindas foi recebida antes de procurar o usuário em outro lugar.

Fluxo de Trabalho

  1. Evento de captura

    O app ou portal emite um evento de registro concluído com o número de telefone do usuário.

    phone: "+…"

  2. Recupera o nome do cliente

    O sistema recupera o nome do cliente e o contexto de serviço ou aplicativo do payload de registro.

    phone: "+…"

  3. Construa e envie

    Uma mensagem de template personalizada é construída com duas variáveis de corpo e um botão URL estático.

    POST /sendTemplate

  4. Entregue

    O novo usuário recebe a mensagem de boas-vindas do WhatsApp e pode abrir sua conta pelo botão.

    delivered

  5. Status rastreado

    O resultado da entrega é registrado para análise de integração ou acompanhamento de suporte.

    status: "read"

WhatsApp Business API for registration welcome message

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave da API
  2. Conta comercial do WhatsApp · Como conectar o WABA
  3. Modelo de WhatsApp · Como Aprovar o Modelo WABA
  4. Consentimento do Cliente · Como Gerenciar o Consentimento

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_SERVICE="___"         # {{2}} service name

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_SERVICE=$TEST_SERVICE"; 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}} service name → ${TEST_SERVICE}
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_SERVICE}" }
      ]
    }

  ]
}
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 Entendido.Resposta
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

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

  • id

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

A entrega em si chega mais tarde, como um retorno separado. Registre um webhook (POST …/webhook) e 1MSG POSTs atualizações de status para seu endpoint HTTPS em um payload top-level hooks[].

200 OKWebhook de status de entrega — payload recebido
{
  "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 retorno da chamada 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 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.

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