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

WhatsApp Business API para contato inicial com um novo lead

O cenário envia um novo lead um template personalizado de WhatsApp como o primeiro contato de vendas.

Visão geral do caso de uso

O cenário envia um novo lead um modelo personalizado de WhatsApp como o primeiro contato de vendas. A mensagem inclui o nome do lead, o nome do especialista e de onde a solicitação veio. Botões de resposta rápida permitem que o lead toque em «Sim, interessado» ou «Me ligue mais tarde»; os toques chegam via webhook para roteamento para vendas ou agendamento.

Exemplo de modelo

Olá, {{1}}! Meu nome é {{2}}, e estou entrando em contato a respeito da sua solicitação de {{3}}. Estou pronto para te contar mais e responder todas as suas perguntas — escolha uma opção conveniente abaixo.

Sim, interessado.
  • {{1}}
    nome do lead ou cliente
  • {{2}}
    Nome do especialista ou gerente se apresentando.
  • {{3}}
    fonte de leads ou contexto de solicitação (por exemplo, formulário do site, anúncio no Instagram, indicação de parceiro)
  • “Sim, interessado.”
    botão — fixado no template Meta
WhatsApp Business API for first contact with a new lead

Quando usar

Aproveite este cenário quando um novo lead chega de um formulário de website, anúncio ou CRM e você precisa de um primeiro contato rápido no WhatsApp enquanto o interesse ainda está alto — mas eles não têm um chat aberto, então apenas um modelo aprovado pode ser enviado primeiro. Isso se encaixa em funis de geração de leads, equipes B2B e de serviços onde um gerente nomeado deve se apresentar, e agências que conectam webhooks de formulários ou plataformas de anúncios ao primeiro contato de saída do 1MSG.

Toque inicial mais rápido enquanto o interesse está alto
Um formulário, anúncio ou evento de lead de CRM resolve o telefone, nome do especialista e rótulo de origem do payload e dispara o template aprovado imediatamente, para que o contato aconteça pelo WhatsApp, em vez de esperar por uma ligação fria ou um e-mail que fica sem ser lido.
Olá! Como você está? Estou aqui para ajudar no que precisar.
Três variáveis de corpo carregam o nome do líder, o especialista se apresentando e de onde veio a consulta, então a primeira mensagem parece um acompanhamento nomeado ao invés de uma divulgação em massa.
Sinal de interesse instantâneo para vendas
Dois botões de resposta rápida — «Sim, interessado» e «Me ligue mais tarde» — estão fixos no modelo Meta; cada toque chega via webhook para que as vendas possam direcionar leads quentes ou agendar retornos de chamada dentro da janela da sessão.
Nada de copiar e colar manualmente.
A integração captura o evento de novo lead e envia o template personalizado com todas as três variáveis de corpo nesse gatilho, para que os representantes não precisem reescrever nomes, fontes ou introduções para cada lead recebido.
Follow-up registrado onde o lead começou
Delivery status and button engagement return by webhook and are written back to the CRM, so the same record that captured the lead shows whether they tapped interest or asked to be called later.

Fluxo de Trabalho

  1. Evento capturado

    Um novo evento de lead é capturado de um formulário, anúncio ou CRM.

    phone: "+…"

  2. Telefone

    O telefone do lead, o nome do especialista e o rótulo da fonte são resolvidos a partir da carga útil.

    phone: "+…"

  3. Construa e envie

    Um template de primeiro contato personalizado é enviado com três variáveis de corpo e dois botões de resposta rápida.

    POST /sendTemplate

  4. Status rastreado

    O lead clica em «Sim, interessado» ou «Me ligue depois» — o evento chega via webhook para roteamento de vendas.

    status: "read"

  5. Entregue

    A entrega e o engajamento são registrados no CRM para acompanhamento.

    delivered

WhatsApp Business API for first contact with a new lead

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a Chave da API
  2. Conta do WhatsApp Business · Como Conectar o WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo do WABA
  4. Aceite do Cliente · Como Gerenciar o Consentimento dos Clientes
  5. Ponto de extremidade do Webhook · Como Configurar Webhooks

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_LEADNAME="___"         # {{1}} lead name
TEST_SPECIALIST="___"         # {{2}} specialist name
TEST_LEADSOURCE="___"         # {{3}} lead source

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_LEADNAME=$TEST_LEADNAME" \
            "TEST_SPECIALIST=$TEST_SPECIALIST" \
            "TEST_LEADSOURCE=$TEST_LEADSOURCE"; 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}} lead name → ${TEST_LEADNAME}
# {{2}} specialist name → ${TEST_SPECIALIST}
# {{3}} lead source → ${TEST_LEADSOURCE}
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_LEADNAME}" },
        { "type": "text", "text": "${TEST_SPECIALIST}" },
        { "type": "text", "text": "${TEST_LEADSOURCE}" }
      ]
    }

  ]
}
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 — e não que ela já chegou ao telefone do cliente. Salve o campo id (que parece wamid.…) para correlacionar as notificações 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 isso; os retornos de chamada 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 o 1MSG envia atualizações de status para seu endpoint HTTPS em um payload hooks[] de nível superior.

200 Entendido!Webhook 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

    Correlaciona o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber retornos de chamada, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída dentro de segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando 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 pelo Meta.

Relacionado

Engajamento de Leads & Conversão
WhatsApp Business API para consulta antes da compra
O cenário envia ao cliente uma mensagem de template personalizada pelo WhatsApp, convidando-o para uma consulta pré-compra.
Engajamento de Leads & Conversão
WhatsApp Business API para notificação de novos leads
O cenário envia um template personalizado de WhatsApp para o gerente de vendas quando um novo lead é capturado.
Engajamento de Leads & Conversão
WhatsApp Business API para qualificação de leads.
Esse caso de uso envia um novo lead um modelo de WhatsApp com uma saudação personalizada: a mensagem substitui o nome do lead e o contexto do produto.
Engajamento de Leads & Conversão
WhatsApp Business API para follow-up de leads sem resposta
O cenário envia ao lead um modelo de WhatsApp personalizado quando ele não responde a uma mensagem de vendas anterior dentro do tempo esperado.
Engajamento de Leads & Conversão
WhatsApp Business API para passagem de leads para vendas
O cenário envia ao cliente um modelo de WhatsApp personalizado quando seu lead qualificado é repassado para a equipe de vendas.
Engajamento de Leads & Conversão
WhatsApp Business API para envio de proposta comercial
O cenário envia ao prospect um modelo de WhatsApp personalizado quando uma proposta comercial está pronta.
Engajamento de Leads & Conversão
WhatsApp Business API para esclarecer a necessidade.
O cenário envia ao lead um modelo personalizado de WhatsApp pedindo que esclareça seu propósito.
Engajamento de Leads & Conversão
WhatsApp Business API para acompanhamento sem resposta
O cenário envia ao cliente um template personalizado pelo WhatsApp quando ele não responde a uma mensagem de serviço anterior dentro do tempo esperado.

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