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

WhatsApp Business API para notificação de fatura mensal

O cenário envia ao cliente um template personalizado de WhatsApp quando uma fatura mensal é emitida.

Visão geral do caso de uso

O cenário envia ao cliente um modelo personalizado de WhatsApp quando uma fatura mensal é emitida. A mensagem inclui o nome do cliente, o nome do serviço, o valor da fatura e a data de vencimento. Um botão de URL estático abre a página de pagamento.

Exemplo de modelo

Olá, {{1}}! Sua fatura mensal para "{{2}}" é {{3}}. Pagamento devido: {{4}}.

Pagar fatura
  • {{1}}
    nome do cliente
  • {{2}}
    nome do serviço ou plano
  • {{3}}
    valor da fatura
  • {{4}}
    data de vencimento do pagamento
  • “Pagar fatura”
    botão — fixo no template Meta
WhatsApp Business API for monthly invoice notification

Quando usá-lo

Procure por este cenário quando a cobrança emite uma fatura mensal recorrente e o cliente não possui um chat aberto no WhatsApp — apenas um modelo aprovado pode enviar a notificação primeiro. Isso se aplica a cobranças de SaaS e assinaturas, utilitários e associações que perdem faturas para filtros de spam, e integradores que conectam horários de cobrança recorrentes à entrega pelo WhatsApp.

Faturas que os clientes realmente veem
O nome do cliente, o serviço, o valor e a data de vencimento chegam como quatro variáveis no corpo da mensagem no WhatsApp, assim a fatura fica no chat que eles verificam diariamente, ao invés de em uma pasta de e-mail que eles ignoram.
Pagamento sem precisar caçar um link
Um botão de URL estático rotulado Pagar fatura abre a página de pagamento online; a URL está fixada no modelo Meta, então somente as quatro variáveis do corpo são enviadas via API.
Nenhum aviso de fatura manual
A cobrança dispara um evento de fatura mensal emitida, o sistema resolve os campos de telefone e fatura, e o template personalizado é enviado sem que alguém precise reescrever os valores ou datas de vencimento.
Entrega registrada para acompanhamento de cobrança
O resultado do envio é registrado para faturamento ou CRM, para que as equipes possam tentar novamente ou escalar quando um aviso de fatura não chega ao cliente.

Fluxo de Trabalho

  1. Gatilho

    Problemas de cobrança geram uma fatura mensal e disparam um evento.

    event · triggered

  2. Captura de evento

    O sistema resolve os campos de telefone e fatura do cliente.

    phone: "+…"

  3. Construa & envie

    Uma mensagem de modelo personalizada é construída com quatro variáveis de corpo e um botão de URL estático.

    POST /sendTemplate

  4. Entregue

    O cliente recebe a notificação da fatura pelo WhatsApp e pode pagar pelo botão.

    delivered

  5. Status rastreado

    O resultado da entrega é registrado para cobrança ou acompanhamento de CRM.

    status: "read"

WhatsApp Business API for monthly invoice notification

Implementação técnica

Pré-requisitos

  1. Chave da API 1MSG · Como obter a chave da API
  2. Conta do WhatsApp Business · Como Conectar WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo WABA
  4. Consentimento do cliente · Como Gerenciar o Consentimento

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_SERVICE="___"         # {{2}} service name
TEST_PAYMENTAMOUNT="___"         # {{3}} payment amount
TEST_DUEDATE="___"         # {{4}} due date

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_SERVICE=$TEST_SERVICE" \
            "TEST_PAYMENTAMOUNT=$TEST_PAYMENTAMOUNT" \
            "TEST_DUEDATE=$TEST_DUEDATE"; 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}} service name → ${TEST_SERVICE}
# {{3}} payment amount → ${TEST_PAYMENTAMOUNT}
# {{4}} due date → ${TEST_DUEDATE}
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_SERVICE}" },
        { "type": "text", "text": "${TEST_PAYMENTAMOUNT}" },
        { "type": "text", "text": "${TEST_DUEDATE}" }
      ]
    }

  ]
}
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 campo id (parece com 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 usam isso como chave.

A entrega em si chega mais tarde, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG POSTs atualizações de status para seu endpoint HTTPS em um payload hooks[] de nível superior.

200 Entendido!Webhook de status de entrega — payload recebido.
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    enviado, entregue, lido — 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 retornos de chamada, consulte GET {base}/{channel}/hookInfo?messageId=<id> em vez disso. Na prática, a entrega frequentemente é concluída em 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.

Perguntas Frequentes

Sim — mensagens de WhatsApp de início frio requerem um template aprovado pelo Meta.

Relacionado

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