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

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.

Visão geral do caso de uso

Esse caso de uso envia a um novo lead um modelo aprovado de WhatsApp com uma saudação personalizada: a mensagem substitui o nome do lead e o contexto do produto ou fonte, e o botão de resposta rápida «Начать» (Iniciar) abre um fluxo de qualificação curto. Após o botão ser pressionado, dentro da janela de sessão de 24 horas, o sistema faz perguntas de acompanhamento uma de cada vez e registra cada resposta via webhook.

Exemplo de template

Olá,{{1}}! Para encontrar a solução certa para{{2}}responda algumas perguntas curtas mais rápido. Clique em «Начать» — leva alguns minutos.

Iniciar
  • {{1}}
    nome do lead ou do destinatário
  • {{2}}
    contexto de interesse do produto ou fonte de leads (de onde veio a solicitação, qual área é de interesse)
  • “Iniciar”
    botão — fixado no template Meta
WhatsApp Business API for lead qualification through key questions

Quando usar isso

Acesse este cenário quando um novo lead chegar de um formulário, anúncio ou CRM com apenas dados de contato básicos e as vendas precisarem de um perfil estruturado — orçamento, cronograma, tamanho da empresa, caso de uso — antes da primeira chamada, mas o WhatsApp ainda não tiver uma sessão aberta. Isso se adequa a equipes de desenvolvimento, pequenos grupos de produtos e agências integrando o WhatsApp no funil de qualificação, onde uma pergunta de modelo não consegue capturar todo o perfil.

Contato inicial em conformidade sem um chat aberto
Um modelo aprovado com duas variáveis de corpo — nome e produto ou contexto da fonte — além de um botão de resposta rápida "Iniciar" é a única maneira de abrir a conversa quando ainda não existe uma sessão de 24 horas.
Perfil completo de qualificação em um único tópico
Depois que o lead clica em Começar, as perguntas de acompanhamento são enviadas uma por vez dentro da janela da sessão e cada resposta chega via webhook, assim o orçamento, o cronograma, o tamanho da empresa e o caso de uso se organizam em um perfil estruturado em vez de um único campo de template.
Menos abandono de formulários
O lead responde perguntas curtas no WhatsApp após uma saudação personalizada, em vez de completar um longo formulário na web que talvez nunca finalize.
Transferência mais rápida para vendas ou CRM
Uma vez que todos os campos principais estão armazenados no perfil de qualificação, o integrador passa o registro completo para o CRM ou vendas para roteamento — nenhum representante digita novamente as respostas de canais dispersos.
Fica dentro da janela da sessão
As perguntas de acompanhamento são enviadas logo após cada resposta do webhook enquanto a janela de 24 horas permanece aberta após o toque no Iniciar, portanto, perguntas posteriores não requerem outro modelo aprovado.

Fluxo de Trabalho

  1. Construa e envie

    Quando um novo lead aparece, o sistema envia um modelo de saudação personalizado e um convite para iniciar um breve fluxo de qualificação.

    POST /sendTemplate

  2. Status verificado

    O lead clica em «Начать» — o evento chega via webhook e uma sessão é aberta na janela do WhatsApp de 24 horas.

    status: "read"

  3. Dentro da sessão

    Dentro da sessão, o integrador envia perguntas de acompanhamento uma de cada vez (orçamento, cronograma, tamanho da empresa, caso de uso).

    POST /sendTemplate

  4. Cada resposta é registrada

    Cada resposta é capturada via webhook e armazenada no perfil de qualificação.

    status: "read"

  5. Entregue

    Após a coleta de todos os campos-chave, o perfil é enviado para o CRM ou vendas para acompanhamento.

    delivered

WhatsApp Business API for lead qualification through key questions

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 de WhatsApp · Como Aprovar o Template do WABA
  4. Consentimento 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_PRODUCTCONTEXT="___"         # {{2}} product context

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_PRODUCTCONTEXT=$TEST_PRODUCTCONTEXT"; 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}} product context → ${TEST_PRODUCTCONTEXT}
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_PRODUCTCONTEXT}" }
      ]
    }

  ]
}
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 1MSGaceitoa mensagem para enviar — não que já tenha chegado ao telefone do cliente.idcampo (parece incompleto)wamid.…) para correlacionar chamadas de entrega.

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

    Aceito para envio —nãoainda no telefone do cliente

  • id

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

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

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

    Correlaciona a chamada com aidretornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você prefere não receber chamadas de retorno, não se inscreva.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 com início frio requerem um modelo aprovado pelo Meta.

Relacionado

Engajamento de Leads & Conversão
WhatsApp Business API para lembrete de acompanhamento de propostas
O cenário envia ao prospect um modelo de mensagem personalizada pelo WhatsApp, lembrando-o de revisar a proposta comercial.
Engajamento de Leads & Conversão
WhatsApp Business API para catálogo de produtos interativo
Este cenário envia uma lista interativa com sendList durante a janela de sessão de 24 horas.
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 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 contato inicial com um novo lead
O cenário envia um novo lead um template personalizado de WhatsApp como o primeiro contato 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.

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