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

WhatsApp Business API para solicitação de confirmação de dados ou assinatura

O cenário envia ao cliente um modelo WhatsApp personalizado quando eles devem assinar um documento ou confirmar dados enviados para continuar.

Visão geral do caso de uso

O cenário envia ao cliente um modelo de WhatsApp personalizado quando é necessário assinar um documento ou confirmar dados enviados para continuar. A mensagem inclui o nome do cliente, o rótulo do documento ou processo e as instruções de assinatura. Um botão de URL estático abre o portal de assinatura ou confirmação de dados.

Modelo de exemplo

Olá, {{1}}! Por favor, revise e assine seu {{2}}. {{3}} Toque no botão abaixo para assinar ou confirmar seus dados. Se você tiver perguntas — estamos aqui para ajudar.

Assinar documento
  • {{1}}
    nome do cliente
  • {{2}}
    documento ou processo a ser assinado (por exemplo, contrato de serviço, solicitação de empréstimo, confirmação de dados)
  • {{3}}
    instruções de assinatura ou confirmação (por exemplo, revisar os termos e assinar eletronicamente no portal até sexta-feira)
  • “Assinar documento”
    botão — fixado no modelo da Meta
WhatsApp Business API for signature or data confirmation request

Quando usar isso

Acesse este cenário quando um cliente precisa assinar um documento ou confirmar os dados enviados antes que o onboarding, a conformidade ou um pedido de serviço possam prosseguir — e ele ainda não completou a etapa, sem uma conversa aberta no WhatsApp para contatá-lo durante a sessão. Isso se aplica a equipes de produto que aguardam assinaturas de contratos, fluxos de fintech que precisam de dados de aplicação confirmados antes da aprovação, e agências conectando gates de CRM, BPM ou provedores de assinatura eletrônica a lembretes de assinatura via WhatsApp.

Assinaturas coletadas sem acompanhamento por e-mail
Três campos carregam o nome do cliente, o rótulo do documento ou processo e as instruções de assinatura, para que a solicitação explique exatamente o que assinar ou confirmar em vez de um aviso genérico "completar seu perfil".
Portal de assinatura a um toque
Um botão de URL estático rotulado como Assinar documento abre o portal de assinatura eletrônica ou confirmação de dados — o link é fixo no modelo aprovado da Meta, enquanto apenas o texto do corpo é enviado via API.
alcance clientes fora da janela de 24 horas
Como não há uma conversa ativa, o envio utiliza um modelo de WhatsApp aprovado via API do 1MSG — o único canal que pode solicitar uma assinatura quando o cliente não escreveu primeiro.
Sem acompanhamento manual para cada assinatura pendente
Quando um gatilho que requer assinatura ou confirmação é ativado a partir do onboarding, conformidade ou suporte, o sistema resolve o número de telefone e envia o modelo nesse evento em vez de alguém copiar as instruções de assinatura manualmente.
Entrega registrada para como funciona acompanhamento
O resultado da entrega é registrado após o envio, para que as equipes de CRM ou de conformidade possam ver quem foi solicitado a assinar e lidar com erros de acordo com as regras da plataforma.

Como funciona

  1. Ações do cliente

    Uma regra de negócio ou fluxo de trabalho exige que o cliente assine um documento ou confirme os dados enviados.

    user action

  2. Capturar evento

    O sistema detecta o evento de assinatura ou confirmação requerida e resolve o número de telefone do destinatário.

    phone: "+…"

  3. Construir & enviar

    Uma mensagem de modelo personalizado é construída com três variáveis de corpo e um botão de URL estático.

    POST /sendTemplate

  4. Entregue

    O cliente recebe a solicitação de assinatura do WhatsApp ou de confirmação de dados com o contexto do processo e instruções.

    delivered

  5. Status rastreados

    O resultado da entrega está registrado; o cliente pode assinar ou confirmar através do link do portal.

    status: "read"

WhatsApp Business API for signature or data confirmation request

Implementação técnica

Pré-requisitos

  1. 1MSG API Key · Como obter API Key
  2. Conta WhatsApp Business · Como Conectar WABA
  3. WhatsApp Modelo · Como Aprovar o Modelo WABA
  4. Opt-in do cliente · Como Gerenciar o Consentimento dos Clientes

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_PROCESS="___"         # {{2}} process name
TEST_NEXTSTEP="___"         # {{3}} next step

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_PROCESS=$TEST_PROCESS" \
            "TEST_NEXTSTEP=$TEST_NEXTSTEP"; 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}} process name → ${TEST_PROCESS}
# {{3}} next step → ${TEST_NEXTSTEP}
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_PROCESS}" },
        { "type": "text", "text": "${TEST_NEXTSTEP}" }
      ]
    }

  ]
}
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 1MSG aceitou a mensagem para envio — não que ela já tenha chegado ao telefone do cliente. Salve o id campo (parecido com wamid.…) para correlacionar os callbacks de entrega.

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

    Accepted for sending — não ainda no telefone do cliente

  • id

    Armazene-o; os callbacks de entrega e hookInfo são baseados nisso

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 que você recebe
{
  "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 send

  • timestamp

    segundos Unix, como uma string

Se você preferir não receber chamadas de retorno, consulte 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

Serviço ao Cliente
WhatsApp Business API para confirmação de recebimento de documentos
O cenário envia ao cliente um modelo de WhatsApp personalizado quando os documentos necessários são recebidos e registrados no back office.
Serviço ao Cliente
WhatsApp Business API para esclarecimento de dados de verificação
O cenário envia ao cliente um modelo WhatsApp personalizado se a verificação de identidade ou KYC não puder ser concluída até dados específicos serem aclarados.
Serviço ao Cliente
WhatsApp Business API para notificação de reativação da conta
O cenário envia ao titular da conta um modelo personalizado do WhatsApp quando uma revisão ou verificação da conta é concluída e o acesso é restaurado.
Serviço ao Cliente
WhatsApp Business API para notificação de verificação rejeitada
O cenário envia ao cliente um modelo de WhatsApp personalizado quando sua eKYC ou verificação de identidade é rejeitada.
Serviço ao Cliente
WhatsApp Business API para confirmação de sucesso da verificação
O cenário envia ao cliente um modelo de WhatsApp personalizado quando a verificação de identidade ou eKYC é aprovada.
Serviço ao Cliente
WhatsApp Business API para notificação de status de verificação
O cenário envia ao cliente um modelo de WhatsApp personalizado quando o status de verificação ou eKYC deles muda.
Serviço ao Cliente
WhatsApp Business API para solicitação de upload de documentos
O cenário envia um modelo de WhatsApp personalizado ao cliente quando um documento necessário está faltando e ele deve carregá-lo para continuar.
Serviço ao Cliente
WhatsApp Business API para notificação de transferência
O cenário envia para o cliente um modelo personalizado de WhatsApp quando um chamado de suporte é transferido para outro departamento.

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