WhatsApp Business API para pesquisa rápida com botão
Este cenário envia ao cliente um curto modelo personalizado de WhatsApp pedindo um feedback rápido.
visão geral do caso de uso
Este cenário envia ao cliente um modelo de WhatsApp curto e personalizado pedindo um feedback rápido. A mensagem inclui o nome dele e o tópico que está sendo avaliado (por exemplo, uma entrega ou visita recente). Dois ou três botões de resposta rápida permitem que ele escolha uma avaliação em um toque; cada escolha chega via webhook para CRM ou análise.
Modelo
Olá, {{1}}! Como foi {{2}}? Escolha uma opção abaixo — leva apenas alguns segundos. Obrigado, seu feedback nos ajuda a melhorar.
- {{1}}nome do cliente
- {{2}}tópico ou assunto sendo avaliado (por exemplo, entrega recente, visita, caso de suporte)
- “Excelentíssimo”botão — fixado no modelo da Meta

Quando usar isso
Acesse este cenário quando precisar de uma pulso de satisfação estruturado rápido após um pedido, visita, entrega ou caso de suporte, e não houver chat aberto no WhatsApp — apenas um modelo aprovado pode iniciar a conversa. Ele se encaixa em equipes de varejo e entrega avaliando a experiência pós-pedido, empresas de serviços perguntando sobre um compromisso recente, e equipes de suporte ou SaaS realizando CSAT no chat após o fechamento sem enviar clientes para links de pesquisa externa.
Como funciona
- Construir & enviar
O CRM ou Como funciona do produto dispara um gatilho de feedback pós-interação quando uma pesquisa está pendente.
POST/sendTemplate - Capture event
O telefone do cliente, nome e tópico da pesquisa são resolvidos a partir dos dados do gatilho ou registro do CRM.
phone:"+…" - Um modelo personalizado é
Um modelo personalizado é enviado com duas variáveis de corpo e botões de avaliação de resposta rápida.
POST/sendTemplate - Status rastreado
O cliente clica em um botão de avaliação — o evento chega via webhook e é registrado como feedback estruturado.
status:"read" - Entregue
CRM ou análises armazenam a pontuação; classificações baixas podem direcionar para um acompanhamento dentro da janela da sessão.
delivered

Implementação técnica
Pré-requisitos
- 1MSG API Key · Como obter a chave da API
- Conta do WhatsApp Business · Como Conectar WABA
- Modelo WhatsApp · Como Aprovar o Modelo WABA
- Opt-in do cliente · Como Gerenciar o Consentimento dos Clientes
- Webhook · Como Configurar webhook
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
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"; 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}
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}" }
]
}
]
}
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 já tenha chegado ao telefone do cliente. Salve o id campo (parece wamid.…) para correlacionar os callbacks de entrega.
{
"sent": true,
"id": "wamid.HBgLMzgwNjM5...",
"message": "Message accepted for delivery"
}sentAceito para envio — não ainda no telefone do cliente
idArmazene isso; as chamadas de retorno de entrega e
hookInfoestão vinculadas a isso
Delivery itself arrives later, as a separate callback. Register a webhook (POST …/webhook) and 1MSG POSTs status updates to your HTTPS endpoint in a top-level hooks[] payload.
{
"hooks": [
{
"id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
"type": "message",
"status": "sent",
"timestamp": "1654864094",
"recipient_id": "556123122026"
}
]
}statussent,delivered,read— ou um status de falha quando aplicávelidCorrelaciona o callback com o
idretornado pela chamada de enviotimestampSegundos Unix, como uma string
Se você preferir não receber callbacks, faça polling 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. |

