WhatsApp Business API para reserva de cita — whatsapp flow

Descripción del caso de uso

Este escenario envía un punto de entrada de WhatsApp Flow con sendFlow durante la ventana de servicio al cliente de 24 horas. Un saludo personalizado más el CTA Reservar ahora abre el formulario del flow publicado.

Ejemplo de plantilla

Hola {{1}}, reserva tu cita:

• {{1}}
  nombre del cliente en el texto de invitación al flow

Cuándo usarlo

Usa este escenario cuando un cliente expresa intención de reservar durante una sesión activa de WhatsApp y necesitas capturar fecha y hora con campos estructurados que el chat libre no puede validar. Encaja en flujos de citas de servicio para desarrolladores, equipos pequeños y agencias que ya tienen un Meta Flow publicado y quieren que el cliente agende sin salir del hilo.

Flujo de trabajo

1. Disparador

   Un cliente expresa intención de reservar mientras la sesión está abierta.

   evento · disparado

2. Capturar evento

   Tu backend obtiene el nombre del cliente y el id del flow.

   phone: "+…"

3. Construir y enviar

   sendFlow envía el saludo con el CTA Reservar ahora.

   POST /send_flow

4. Entregado

   El cliente completa el formulario del flow y los datos de reserva regresan a tu sistema.

   entregado

Implementación técnica

Requisitos previos

1. Clave API de 1MSG · Cómo obtener la clave API
2. Cuenta de WhatsApp Business · Cómo conectar WABA
3. Ventana de sesión de 24 horas abierta · Cómo funciona la ventana de 24 horas
4. Opt-in del cliente · Cómo gestionar el consentimiento
5. Endpoint de webhook · Cómo configurar webhooks

Ejemplos 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

Respuesta y estado de entrega

HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente. Guarda el campo id (tipo wamid.…) para correlacionar los callbacks de entrega.

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

La entrega llega después, como un callback aparte. Registra un webhook (POST …/webhook) y 1MSG enviará las actualizaciones de estado a tu endpoint HTTPS en un payload hooks[] de nivel superior.

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

Si prefieres no recibir callbacks, consulta GET {base}/{channel}/hookInfo?messageId=<id> en su lugar. En la práctica la entrega suele completarse en segundos — pero el contrato de la API no lo garantiza, así que nunca bloquees un flujo esperándola.

Errores frecuentes

Preguntas frecuentes