Skill de IA para API do WhatsAppMais
1msg official logo

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.

Visão geral do caso de uso

O cenário envia ao cliente um modelo de WhatsApp personalizado quando um documento requerido está faltando e eles devem enviá-lo para continuar. A mensagem inclui o nome do cliente, o tipo de documento e instruções de upload. Um botão de URL estático abre o portal de upload de documentos ou formulário seguro.

Modelo exemplo

Olá, {{1}}! Por favor, faça o upload do seu {{2}}. {{3}} Toque no botão abaixo para fazer o upload do seu documento. Se você tiver perguntas — estamos aqui para ajudar.

Carregar documento
  • {{1}}
    nome do cliente
  • {{2}}
    documento para upload (por exemplo, escaneio de passaporte, comprovante de endereço, declaração de renda)
  • {{3}}
    instruções de envio (por exemplo, formato PDF ou foto, enviar até sexta-feira)
  • “Carregar documento”
    botão — fixo no modelo da Meta
WhatsApp Business API for document upload request

Quando usar

Atingir este cenário quando um cliente deve enviar um documento necessário para continuar o onboarding, completar uma solicitação de suporte ou desbloquear um recurso da conta — e ele ainda não o enviou, sem uma conversa aberta no WhatsApp para contatá-lo durante a sessão. Isso se encaixa em equipes de produto que bloqueiam a ativação da conta devido à falta de arquivos KYC, equipes de suporte aguardando anexos ou formulários assinados, e agências conectando portões de documentos no CRM ou BPM em lembretes de upload pelo WhatsApp.

Documentos ausentes coletados sem acompanhamento por email
Três variáveis do corpo carregam o nome do cliente, o tipo de documento e as instruções de upload, para que a solicitação explique exatamente o que enviar em vez de um aviso genérico "por favor, complete seu perfil".
Portal de upload a um toque de distância
Um botão de URL estático rotulado como Carregar documento abre o portal ou formulário de upload seguro — 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
Porque não há uma conversa ativa, o envio utiliza um modelo de WhatsApp aprovado via API 1MSG — o único canal que pode solicitar o envio de um documento quando o cliente não escreveu primeiro.
Nenhum acompanhamento manual para cada arquivo ausente
Quando um gatilho que requer o upload de documento é acionado a partir do onboarding, suporte ou conformidade, o sistema resolve o número de telefone e envia o modelo nesse evento, em vez de alguém copiar as instruções de upload manualmente.
Entrega registrada para como funciona acompanhamento
O resultado da entrega é registrado após o envio, para que as equipes de CRM ou suporte possam ver quem foi solicitado a fazer o upload e lidar com os erros de acordo com as regras da plataforma.

Como funciona

  1. Gatilho

    Uma regra de negócios ou como funciona exige que o cliente faça o upload de um documento específico.

    event · triggered

  2. Evento de captura

    O sistema detecta o evento «envio-de-documento-requerido» e resolve o número de telefone do destinatário.

    phone: "+…"

  3. Construir & enviar

    Uma mensagem de modelo personalizada é 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 upload de documentos pelo WhatsApp com o contexto do documento e instruções.

    delivered

  5. Status rastreado

    O resultado da entrega está registrado; o cliente pode fazer o upload através do link do portal.

    status: "read"

WhatsApp Business API for document upload request

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 do WhatsApp · Como Aprovar 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_AWAITEDITEM="___"         # {{2}} awaited item
TEST_REQUESTDETAIL="___"         # {{3}} request detail

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_AWAITEDITEM=$TEST_AWAITEDITEM" \
            "TEST_REQUESTDETAIL=$TEST_REQUESTDETAIL"; 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}} awaited item → ${TEST_AWAITEDITEM}
# {{3}} request detail → ${TEST_REQUESTDETAIL}
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_AWAITEDITEM}" },
        { "type": "text", "text": "${TEST_REQUESTDETAIL}" }
      ]
    }

  ]
}
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 ela já tenha chegado ao telefone do cliente. Salve o id campo (parece como 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; 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

    Correla o callback com o id retornado pela chamada send

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber callbacks, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega geralmente é concluída em poucos segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando 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 início frio no WhatsApp requerem um modelo aprovado pela Meta.

Relacionado

Serviço ao Cliente
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.
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 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.
Serviço ao Cliente
WhatsApp Business API para notificação de status de ticket
O cenário envia ao cliente um modelo de WhatsApp personalizado quando o status de um ticket de suporte muda.
Serviço ao Cliente
WhatsApp Business API para notificação de escalonamento
O cenário envia ao cliente um template de WhatsApp personalizado quando um ticket de suporte é escalado porque a resolução está levando mais tempo que o usual.
Serviço ao Cliente
WhatsApp Business API para notificação de ticket criado
O cenário envia ao cliente um modelo personalizado de WhatsApp quando um novo chamado de suporte é criado.

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