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
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
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
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"
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
Cada resposta é registrada
Cada resposta é capturada via webhook e armazenada no perfil de qualificação.
status: "read"
Entregue
Após a coleta de todos os campos-chave, o perfil é enviado para o CRM ou vendas para acompanhamento.
#!/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.
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
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
Status
Resposta
Causa
200
Message was not sent: template is not defined
namespace, template or language missing from the request body.
200
template name (…) does not exist in <language>
The template is approved in a different language than the one requested.
200
Message was not sent: provide chatId, phone, bsuid, or username
No recipient the channel could resolve.
403
access denied
The token is wrong, or belongs to a different channel than the URL.
429
too many requests. please try later
The channel is over its send rate.
Perguntas Frequentes
Sim — mensagens de WhatsApp com início frio requerem um modelo aprovado pelo Meta.