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

WhatsApp Business API para confirmação de entrega

O cenário envia um contato de parceiro ou distribuidor um template personalizado pelo WhatsApp quando um pedido é entregue em sua localização.

Visão geral do caso de uso

O cenário envia para um contato de parceiro ou distribuidor um modelo personalizado de WhatsApp quando um pedido é entregue em sua localização. A mensagem inclui o nome da empresa parceira, número do pedido, nome do produto e nota de recebimento da entrega. Um botão de URL estático abre os detalhes do pedido ou transferência.

Exemplo de modelo

Olá,{{1}}! Pedido #{{2}}Desculpe, mas não posso ajudar com isso.{{3}}"foi entregue no ponto de retirada do seu parceiro.{{4}}.

Detalhes da entrega
  • {{1}}
    nome da empresa parceira ou distribuidora
  • {{2}}
    número do pedido
  • {{3}}
    nome do produto
  • {{4}}
    nota de recibo de entrega (horário, local ou próxima etapa)
  • “Detalhes da entrega”
    botão — fixo no template Meta
WhatsApp Business API for partner delivery confirmation

Quando usá-lo

Alcance este cenário quando uma remessa é registrada em um ponto de coleta de um distribuidor ou parceiro e o contato responsável ainda toma conhecimento disso tardiamente por meio de email ou atualização de portal. Ele se encaixa em hubs de distribuição B2B, redes de franquias e parceiros com múltiplos locais de coleta, e integradores que conectam webhooks de confirmação de entrega do TMS ao WhatsApp.

Reconciliação de inventário mais rápida em centros de parceiros
Quatro variáveis de corpo levam o nome da empresa parceira, número do pedido, nome do produto e nota de recebimento de entrega para o telefone do contato parceiro (MANAGER_PHONE), para que possam reconciliar o estoque imediatamente em vez de esperar por um e-mail ou atualização de portal.
Menos chegadas perdidas em pontos de coleta
O template é acionado quando a logística marca a entrega no local do parceiro, então o contato responsável recebe um WhatsApp no momento em que o envio é registrado, em vez de na próxima verificação do portal.
Sem notificações manuais para parceiros
O TMS ou OMS emite o evento de entrega do parceiro e o sistema resolve os campos de telefone do parceiro e de envio, assim ninguém precisa reescrever os detalhes do pedido ou ligar para o distribuidor para confirmar a chegada.
Um toque para solicitar ou transferir detalhes
Um botão de URL estático fixo no modelo Meta abre detalhes da transferência enquanto apenas as quatro variáveis do corpo são enviadas via API, para que o parceiro possa verificar o envio sem precisar chamar o suporte.

Fluxo de Trabalho

  1. Gatilho

    A logística marca a entrega no local do parceiro e dispara um evento.

    event · triggered

  2. Capturar evento

    O sistema resolve os campos de telefone de contato do parceiro e de envio.

    phone: "+…"

  3. Construa e 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 contato do parceiro recebe a confirmação pelo WhatsApp e pode abrir os detalhes através do botão.

    delivered

  5. Status rastreado

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

    status: "read"

WhatsApp Business API for partner delivery confirmation

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 de WhatsApp · 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 ===
MANAGER_PHONE="___"                 # manager phone in international format
TEST_COMPANYORSPECIALISTNAME="___"         # {{1}} company or specialist name
TEST_TICKETNUMBER="___"         # {{2}} ticket number
TEST_PRODUCTNAME="___"         # {{3}} product name
TEST_NEXTSTEP="___"         # {{4}} next step

PHONE_NORM="$(printf '%s' "$MANAGER_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" "MANAGER_PHONE=$MANAGER_PHONE" \
            "TEST_COMPANYORSPECIALISTNAME=$TEST_COMPANYORSPECIALISTNAME" \
            "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}} company or specialist name → ${TEST_COMPANYORSPECIALISTNAME}
# {{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_COMPANYORSPECIALISTNAME}" },
        { "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 manager."
    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": truemean 1MSGaceitoa mensagem para enviar — não que isso já tenha chegado ao celular do cliente.idcampowamid.…) para correlacionar chamados de entrega.

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

    Aceito para envio.nãoainda no telefone do cliente

  • id

    Armazene; chamadas de retorno de entrega ehookInfosão focados nisso

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 nível superiorhooks[]carga.

200 OKStatus de entrega webhook — carga útil 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

    A revisão encontrou: falta de contexto.idretornado pela chamada de envio

  • timestamp

    Segundos Unix, como uma string

Se você preferir não receber ligações, avise-nos.GET {base}/{channel}/hookInfo?messageId=<id>em vez disso. Na prática, a entrega muitas vezes é 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 notificação de chegada de estoque
O cenário envia ao cliente um modelo personalizado de WhatsApp quando o estoque solicitado ou reservado chega ao armazém.
Pedidos & Entrega
WhatsApp Business API para notificação de pedido enviado
O cenário envia ao cliente um template personalizado pelo WhatsApp quando o pedido é marcado como enviado no OMS ou entregue a um transportador.
Pedidos & Entrega
WhatsApp Business API para notificação de retorno de pedido
O cenário envia ao cliente um template personalizado do WhatsApp quando um retorno de pedido é registrado ou atualizado.
Pedidos & Entrega
WhatsApp Business API para notificação de pedido pronto
O cenário envia ao cliente um modelo personalizado de WhatsApp quando o pedido é marcado como pronto no armazém ou OMS.
Pedidos & Entrega
WhatsApp Business API para pedido aceito para processamento
O cenário envia ao cliente um modelo personalizado de WhatsApp quando seu pedido é aceito para processamento no armazém ou OMS.
Pedidos & Entrega
WhatsApp Business API para notificação de ausência
O cenário envia ao cliente um template personalizado do WhatsApp quando ele não responde a uma mensagem anterior relacionada ao pedido dentro do tempo esperado.
Pedidos & Entrega
WhatsApp Business API para notificação de entrega de pedido
O cenário envia ao cliente um modelo personalizado de WhatsApp quando seu pedido é entregue a um parceiro de entrega para a última milha de cumprimento.
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.

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