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

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.

Visão geral do caso de uso

O cenário envia ao cliente um modelo de WhatsApp personalizado quando a entrega do seu pedido é atrasada. A mensagem inclui o nome do cliente, número do pedido, nome do produto e ETA revisado ou motivo do atraso. Um botão de URL estático abre o rastreamento da remessa.

Exemplo de modelo

Olá, {{1}}! Infelizmente, a entrega do pedido #{{2}} para "{{3}}" está atrasada. {{4}}.

Rastrear remessa
  • {{1}}
    nome do cliente
  • {{2}}
    número do pedido
  • {{3}}
    nome do produto
  • {{4}}
    motivo revisado para ETA ou atraso
  • “Rastrear remessa”
    botão — fixo no template da Meta
WhatsApp Business API for delivery delay notification

Quando usá-lo

Aplique este cenário quando um transportador ou armazém relatar um atraso na data de entrega prometida e o cliente pode não ter um thread aberto no WhatsApp — apenas um template aprovado pode alcançá-los primeiro. Isso se aplica a equipes de logística de e-commerce, marketplaces que recebem tickets WISMO após atrasos de transportadoras e integradores que conectam webhooks de atraso de TMS ao WhatsApp outbound.

Menos tickets WISMO recebidos.
O número do pedido, o nome do produto e a nova ETA ou razão do atraso chegam como quatro variáveis no corpo da conversa do cliente, para que eles fiquem sabendo sobre o atraso no WhatsApp antes de abrir um ticket de suporte.
Confiança quando o ETA atrasa
A logística dispara o modelo no evento de atraso enquanto o cliente ainda não tem uma conversa aberta, então um modelo aprovado chega até eles fora da janela de 24 horas em vez de esperar que eles liguem.
Sem atraso manual no contato
O evento de atraso do TMS ou OMS aciona o envio automaticamente, assim nenhum agente reescreve os detalhes do pedido ou procura o telefone do cliente.
Rastreamento sem uma chamada de suporte
O botão de URL estático fixo no modelo Meta abre o rastreamento de envio, para que o cliente possa acompanhar o pacote na mesma mensagem que explica o atraso.
Entrega registrada para acompanhamento do CRM
O resultado da entrega é registrado de volta após o envio, assim o suporte vê o aviso de atraso no registro do pedido sem uma nota separada.

Fluxo de Trabalho

  1. Desencadear

    A logística marca um atraso na entrega e dispara um evento.

    event · triggered

  2. Captura de evento

    O sistema resolve os campos de número de telefone do cliente e de atraso.

    phone: "+…"

  3. Construir & enviar

    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 atualização pelo WhatsApp e pode abrir o rastreamento através do botão.

    delivered

  5. Status rastreado

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

    status: "read"

WhatsApp Business API for delivery delay 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 o WABA
  3. Modelo do WhatsApp · Como Aprovar o Modelo WABA
  4. Aceite 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_TICKETNUMBER="___"         # {{2}} ticket number
TEST_PRODUCTNAME="___"         # {{3}} product name
TEST_NEXTSTEP="___"         # {{4}} 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_TICKETNUMBER=$TEST_TICKETNUMBER" \
            "TEST_PRODUCTNAME=$TEST_PRODUCTNAME" \
            "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}} ticket number → ${TEST_TICKETNUMBER}
# {{3}} product name → ${TEST_PRODUCTNAME}
# {{4}} 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_TICKETNUMBER}" },
        { "type": "text", "text": "${TEST_PRODUCTNAME}" },
        { "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 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

    Accepted for sending — not yet on the customer's phone

  • id

    Armazene isso; as callbacks de entrega e hookInfo são vinculadas a isso.

A entrega em si chega mais tarde, como uma chamada de retorno separada. Registre um webhook (POST …/webhook) e 1MSG publica atualizações de status no seu endpoint HTTPS em um payload de nível superior hooks[].

200 OKWebhook 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

    Correla a chamada com o id retornado pela chamada de envio.

  • 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 segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando por ela.

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 com início a frio requerem 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 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.
Pedidos & Entrega
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.

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