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

WhatsApp Business API para notificação de mudança de status

O cenário envia ao cliente um template personalizado pelo WhatsApp quando o status do seu pedido, solicitação ou requisição muda.

Visão geral do caso de uso

O cenário envia ao cliente um modelo personalizado de WhatsApp quando o status do seu pedido, aplicação ou solicitação muda. A mensagem inclui o nome do cliente, o processo ou entidade sendo acompanhada e o novo rótulo de status. Um botão de URL estático abre a página de status ou o portal do cliente.

Exemplo de template

Olá {{1}}, o status da sua {{2}} foi atualizado para: {{3}}. Você pode ver todos os detalhes em nosso site. Obrigado por continuar conosco — nós o notificaremos sobre quaisquer outras alterações.

Ver status
  • {{1}}
    nome do cliente
  • {{2}}
    processo ou entidade (por exemplo, pedido #12345, solicitação de empréstimo, chamado de suporte)
  • {{3}}
    nova etiqueta de status (por exemplo, Enviado, Em revisão, Aprovado)
  • “Ver status”
    botão — fixo no modelo da Meta
WhatsApp Business API for status change notification

Quando usá-lo

Alcance este cenário quando um pedido, aplicação ou solicitação de serviço avança para uma nova etapa e o cliente deve ser informado sobre isso antes de entrar em contato com o suporte ou atualizar um portal. É adequado para equipes de e-commerce e logística que rastreiam remessas, serviços e negócios B2B que lidam com revisões de empréstimos ou vistos, além de agências conectando webhooks de status de CRM, ERP ou portal personalizado ao WhatsApp.

Menos ligações de "onde está meu pedido?"
Três variáveis principais carregam o nome do cliente, o processo ou entidade que está sendo rastreada, e o novo rótulo de status, de modo que a atualização chega no chat do cliente no WhatsApp em vez de forçar um login no portal ou uma ligação para suporte.
Atualizações sem um chat aberto
O back office, CRM ou integração aciona um modelo aprovado no evento de mudança de status, para que o cliente fique informado sobre a nova etapa mesmo quando não há uma sessão ativa de 24 horas no WhatsApp.
Detalhes a um toque de distância
O botão de URL de status de visualização estática é fixo no template Meta e abre a página de status ou o portal do cliente para qualquer coisa que as três variáveis de corpo não descrevam.
Entrega registrada para acompanhamento de CRM
O sistema resolve o número de telefone a partir da carga útil de status, envia o template e registra o resultado da entrega para que as equipes de back-office lidem com erros no mesmo registro.

Fluxo de Trabalho

  1. Status monitorado

    O back office, CRM ou integração emite um evento de mudança de status.

    status: "read"

  2. Resolve o telefone do destinatário

    O sistema resolve os campos de número de telefone e status do destinatário.

    status: "read"

  3. Crie & envie

    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 notificação do WhatsApp com o status atualizado.

    delivered

  5. Resultado da entrega está registrado

    O resultado da entrega é registrado; os erros são tratados de acordo com as regras da plataforma.

    status: "read"

WhatsApp Business API for status change 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. Opção 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_PROCESS="___"         # {{2}} process name
TEST_STATUS="___"         # {{3}} status label

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_STATUS=$TEST_STATUS"; 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}} status label → ${TEST_STATUS}
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_STATUS}" }
      ]
    }

  ]
}
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 wamid.…) para correlacionar os callbacks de entrega.

200 Entendido!Resposta
{
  "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 retornos de chamada de entrega e hookInfo são indexados nisso.

A entrega em si chega mais tarde, como um callback separado. Registre um webhook (POST …/webhook) e 1MSG envia atualizações de status para seu endpoint HTTPS em um payload de 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 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 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 a frio exigem um modelo aprovado pela Meta.

Relacionado

Pedidos & Entrega
WhatsApp Business API para confirmação de entrega de pedido
O cenário envia ao cliente um modelo personalizado WhatsApp quando seu pedido é marcado como entregue.
Pedidos & Entrega
WhatsApp Business API para notificação de pedido cancelado
O cenário envia ao cliente um modelo de WhatsApp personalizado quando um pedido é cancelado.
Pedidos & Entrega
WhatsApp Business API para notificação de nova rota
O cenário faz com que um gerente ou despachante envie um modelo personalizado de WhatsApp quando uma nova rota ou viagem é criada.
Pedidos & Entrega
WhatsApp Business API para confirmação de novos pedidos
O cenário envia ao cliente um modelo de WhatsApp personalizado logo após um novo pedido ser criado.
Pedidos & Entrega
Notificação de entrega falha no WhatsApp Business API
O cenário envia ao cliente um modelo personalizado de WhatsApp quando uma tentativa de entrega falha.
Pedidos & Entrega
WhatsApp Business API para entrega — compartilhe localização
Este cenário envia uma localização de mapa com sendLocation durante a janela de atendimento ao cliente de 24 horas.
Pedidos & Entrega
WhatsApp Business API para notificação de atraso na entrega
O cenário envia ao cliente um template personalizado pelo WhatsApp quando a entrega do pedido está atrasada.
Pedidos & Entrega
WhatsApp Business API para contato de entregador.
Este cenário envia um cartão de contato do WhatsApp com sendContact durante a janela de atendimento ao cliente após um motorista ser designado ao pedido.

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