WhatsApp Business API para agendamento — fluxo do WhatsApp

Visão geral do caso de uso

Este cenário envia um ponto de entrada do Flow no WhatsApp com sendFlow durante o período de 24 horas de atendimento ao cliente. Uma saudação personalizada mais um CTA de Reserve agora abre o formulário do flow publicado.

Exemplo de modelo

Oi {{1}}, agende sua consulta:

• {{1}}
  nome do cliente no texto do convite de fluxo

Quando usar isso

Use esse cenário quando um cliente expressa intenção de agendar durante uma sessão ativa no WhatsApp e você precisa capturar a data e o horário de forma estruturada que um chat em texto livre não pode validar. Isso se encaixa em fluxos de trabalho de agendamento de serviços para desenvolvedores, pequenas equipes e agências que já possuem um Meta Flow publicado e desejam que o cliente agende sem sair da conversa.

Fluxo de Trabalho

1. Gatilho

   Um cliente expressa intenção de agendamento enquanto a sessão está aberta.

   event · triggered

2. Eventos de captura

   Seu backend resolve o nome do cliente e o id do fluxo.

   phone: "+…"

3. Construir & enviar

   sendFlow envia a saudação com o CTA Reserve agora.

   POST /send_flow

4. Entregue

   O cliente preenche o formulário de fluxo e os dados da reserva retornam para o seu sistema.

   delivered

Implementação técnica

Pré-requisitos

1. Chave da API 1MSG · Como obtê-la
2. Conta do WhatsApp Business · Como Conectar WABA
3. Abra uma janela de sessão de 24 horas · Como funciona a janela de 24 horas
4. Consentimento do cliente · Como Gerenciar o Consentimento dos Clientes
5. Ponto de extremidade de 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)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
FLOW_TOKEN="___"                         # flow token from your backend

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendFlow"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "Hi Alex, book your appointment:",
  "flowId": "1234567890",
  "flowToken": "${FLOW_TOKEN}",
  "flowCta": "Book now",
  "flowAction": "navigate"
}
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."
else
  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 já chegou no telefone do cliente. Salve o campo id (parece com wamid.…) para correlacionar os callbacks de entrega.

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

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

{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}

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 ele.

Erros comuns

Perguntas Frequentes