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

WhatsApp Business API para confirmação de presença

O cenário envia ao cliente um modelo personalizado de WhatsApp perguntando se ele comparecerá a uma visita agendada.

Visão geral do caso de uso

O cenário envia ao cliente um template personalizado de WhatsApp perguntando se ele irá participar de uma visita agendada. Dois botões de resposta rápida permitem que o cliente confirme a presença ou cancele; o webhook direciona a escolha para o seu backend.

Exemplo de template

Olá, {{1}}! Você vai participar do seu {{2}} no dia {{3}} às {{4}}?

Eu irei participar.
  • {{1}}
    nome do cliente
  • {{2}}
    tipo de serviço ou atendimento
  • {{3}}
    data de reserva
  • {{4}}
    tempo de reserva
  • “Eu irei participar.”
    botão — fixo no modelo Meta
WhatsApp Business API for attendance confirmation

Quando usar isso

Aproveite este cenário quando uma visita está no calendário, mas a presença ainda é incerta e o negócio precisa de uma resposta sim-ou-não antes do horário. É ideal para clínicas e salões que perdem horas pagas devido a faltas, equipes de serviços de campo onde uma viagem desperdiçada custa uma rota, e integradores que roteiam confirmações/cancelamentos de webhooks para uma API de agendamento.

Menos slots vazios
Nome, serviço, data e hora são quatro informações, e dois botões de resposta rápida pedem ao cliente para confirmar ou cancelar antes da visita.
Menos tempo de viagem ou de trabalho desperdiçado.
O sistema de agendamento dispara o modelo em um evento de confirmação de presença, para que as equipes de campo ou cadeiras de salão saibam se devem se preparar antes da hora da consulta.
Sem chamadas de confirmação manuais
Os toques de confirmação e cancelamento chegam via webhook e atualizam o status da reserva no agendamento ou CRM, para que ninguém precise contatar o cliente por telefone.
Funciona fora da janela de 24 horas.
Um modelo aprovado chega ao cliente quando não há conversa aberta — uma mensagem em texto livre não é permitida para esta primeira verificação de saída.

Fluxo de Trabalho

  1. Gatilho

    O sistema de agendamento dispara um evento de confirmação de presença.

    event · triggered

  2. Captura de evento

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

    phone: "+…"

  3. Construir & enviar

    Uma mensagem de template personalizada é construída com quatro variáveis de corpo e dois botões de resposta rápida.

    POST /sendTemplate

  4. Entregue

    O cliente recebe a mensagem do WhatsApp e toca em confirmar ou cancelar.

    delivered

  5. Status rastreado

    O webhook atualiza o status da reserva no agendamento ou CRM.

    status: "read"

WhatsApp Business API for attendance confirmation

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 de WhatsApp · Como Aprovar o Modelo WABA
  4. Aproveitamento do cliente · Como Gerenciar o Consentimento
  5. Ponto de extremidade do Webhook · Como Configurar Webhooks

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_BOOKINGDATE="___"         # {{3}} booking date
TEST_BOOKINGTIME="___"         # {{4}} booking time

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_BOOKINGDATE=$TEST_BOOKINGDATE" \
            "TEST_BOOKINGTIME=$TEST_BOOKINGTIME"; 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}} booking date → ${TEST_BOOKINGDATE}
# {{4}} booking time → ${TEST_BOOKINGTIME}
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_BOOKINGDATE}" },
        { "type": "text", "text": "${TEST_BOOKINGTIME}" }
      ]
    }

  ]
}
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á chegou 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 retornos de chamada de entrega e hookInfo são baseados nisso.

A entrega em si chega mais tarde, como um retorno separado. Registre um webhook (POST …/webhook) e 1MSG POSTa atualizações de status para seu endpoint HTTPS em um payload top-level hooks[].

200 ClaroWebhook de status de entrega — carga útil.
{
  "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 send

  • 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 costuma ser concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo aguardando 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 para início a frio requerem um modelo aprovado pelo Meta.

Relacionado

Compromissos & Lembretes
WhatsApp Business API para lembrete de acompanhamento
O cenário envia ao cliente um modelo de WhatsApp personalizado quando um acompanhamento ou visita repetida é necessário.
Compromissos & Lembretes
WhatsApp Business API para confirmação de reagendamento
O cenário envia um modelo de WhatsApp personalizado ao cliente quando uma reserva é remarcada.
Compromissos & Lembretes
WhatsApp Business API para notificação de mudança de reserva
O cenário envia ao cliente um template personalizado de WhatsApp quando os detalhes da reserva mudam.
Compromissos & Lembretes
WhatsApp Business API para confirmação de cancelamento
O cenário envia ao cliente um template personalizado no WhatsApp quando uma reserva é cancelada.
Compromissos & Lembretes
WhatsApp Business API para agendamento — fluxo do WhatsApp
Esse cenário envia um ponto de entrada do WhatsApp com sendFlow durante a janela de atendimento ao cliente de 24 horas.
Compromissos & Lembretes
WhatsApp Business API para lembrete de reserva antecipada
O cenário envia ao cliente um modelo personalizado de WhatsApp vários dias antes de uma visita agendada.
Compromissos & Lembretes
WhatsApp Business API para solicitação de confirmação
O cenário envia ao cliente um modelo personalizado de WhatsApp pedindo para confirmar ou cancelar uma ação planejada.
Compromissos & Lembretes
WhatsApp Business API para confirmação de reserva
O cenário envia ao cliente um template personalizado de WhatsApp imediatamente após a confirmação da reserva.

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