1msg official logo

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.

Excelentíssimo
  • {{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
WhatsApp Business API for quick button survey

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.

Taxas de resposta mais altas do que pesquisas por email
O cliente escolhe uma avaliação com um toque rápido dentro do WhatsApp — nome e tópico aparecem como duas variáveis de corpo — em vez de abrir um link de email que eles ignoram.
Pontuações estruturadas sem perseguir manualmente
O CRM dispara o modelo em um gatilho pós-interação, resolve o telefone e o tópico do registro e armazena cada escolha de botão dos eventos de webhook como feedback pronto para análise.
Respostas enquanto a experiência está fresca
A pesquisa é enviada logo após a entrega, visita ou fechamento do ticket, então a satisfação é registrada no canal que o cliente já utiliza antes que a memória se apague.
Avaliações negativas podem abrir um acompanhamento no mesmo chat
Um atendimento de baixa pontuação chega via webhook dentro da janela da sessão de 24 horas, então a automação ou um gerente pode responder no WhatsApp sem iniciar uma nova campanha de saída.
Mensagem inicial em conformidade quando não há sessão
Um modelo aprovado com duas variáveis de corpo e rótulos de resposta rápida fixos é a única maneira de solicitar feedback quando mensagens de texto livre não são permitidas e nenhuma conversa está aberta ainda.

Como funciona

  1. 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

  2. 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: "+…"

  3. 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

  4. Status rastreado

    O cliente clica em um botão de avaliação — o evento chega via webhook e é registrado como feedback estruturado.

    status: "read"

  5. Entregue

    CRM ou análises armazenam a pontuação; classificações baixas podem direcionar para um acompanhamento dentro da janela da sessão.

    delivered

WhatsApp Business API for quick button survey

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como obter a chave da API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo WhatsApp · Como Aprovar o Modelo WABA
  4. Opt-in do cliente · Como Gerenciar o Consentimento dos Clientes
  5. 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.

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; as chamadas de retorno de entrega e hookInfo estã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.

200 OKWebhook de status de entrega — dados recebidos
{
  "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 o callback com o id retornado pela chamada de envio

  • timestamp

    Segundos 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

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.

FAQ

Sim — mensagens de WhatsApp de início frio exigem um modelo aprovado pela Meta.

Relacionado

Pesquisas & Feedback
WhatsApp Business API para lembrete de conclusão de pesquisa
O cenário envia ao cliente um modelo de WhatsApp personalizado quando um pedido de pesquisa ainda está pendente após a primeira solicitação.
Pesquisas & Feedback
WhatsApp Business API para solicitação de pesquisa pós-visita
O cenário envia um modelo de WhatsApp personalizado ao cliente após a visita ou consulta, pedindo que compartilhe feedback sobre a experiência.
Pesquisas & Feedback
WhatsApp Business API para pesquisa pós-entrega
O cenário envia ao cliente um modelo WhatsApp personalizado após o pedido ser entregue, pedindo para avaliar a qualidade da entrega.
Pesquisas & Feedback
WhatsApp Business API para pesquisa de qualidade de serviço
O cenário envia ao cliente um modelo WhatsApp personalizado após uma interação de serviço, pedindo para avaliar a qualidade do serviço recebido.
Pesquisas & Feedback
WhatsApp Business API para solicitação de revisão pós-compra
O cenário envia ao cliente um modelo de WhatsApp personalizado após a compra, pedindo para avaliar o produto e compartilhar feedback.
Pesquisas & Feedback
WhatsApp Business API para solicitação de avaliação de serviço
O cenário envia ao cliente um modelo de WhatsApp personalizado após a conclusão do serviço, pedindo para avaliar a qualidade do que foi entregue.
Pesquisas & Feedback
WhatsApp Business API para pesquisa de nps após interação
O cenário envia ao cliente um modelo personalizado de WhatsApp após uma interação ser concluída, pedindo que avalie a probabilidade de recomendar o negócio.
Pesquisas & Feedback
WhatsApp Business API para solicitação de csat de suporte
O cenário envia ao cliente um modelo personalizado de WhatsApp após o suporte ser concluído, pedindo que avalie a qualidade do serviço.

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