Enviar un WhatsApp Flow para agendar citas (API)

Este escenario envía un punto de entrada de WhatsApp Flow con sendFlow durante la ventana de servicio al cliente de 24 horas.

Probar la demo Ver ejemplo de código

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

WhatsApp Business API for appointment booking — whatsapp 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.

Campos de agenda validados

El CTA Reservar ahora abre tu Meta Flow publicado dentro de WhatsApp, así las preferencias de fecha y hora llegan como envíos estructurados del formulario en lugar de respuestas ambiguas en texto libre que tu backend tendría que interpretar.

Reserva sin salir del chat

sendFlow se dispara durante la ventana abierta de servicio al cliente de 24 horas, así el cliente completa el formulario del flow en el mismo chat en vez de pasar a correo o a un widget externo de reservas.

Invitación personalizada al flow

Una variable del cuerpo lleva el nombre del cliente en el texto de saludo, así el mensaje sendFlow se lee como una invitación directa antes de que el cliente toque Reservar ahora.

Datos de reserva de vuelta a tu sistema

Cuando el cliente envía el formulario del flow, la carga de finalización regresa a tu CRM o integración de calendario por el webhook del flow, así la agenda no se queda en la pantalla del chat.

Sin fricción de plantilla cold-start

Como el cliente ya está en una sesión abierta, sendFlow entrega el punto de entrada del flow sin abrir una conversación nueva con una plantilla aprobada rígida primero.

Flujo de trabajo

Disparador
Un cliente expresa intención de reservar mientras la sesión está abierta.
evento · disparado
Capturar evento
Tu backend obtiene el nombre del cliente y el id del flow.
phone: "+…"
Construir y enviar
sendFlow envía el saludo con el CTA Reservar ahora.
POST /send_flow
Entregado
El cliente completa el formulario del flow y los datos de reserva regresan a tu sistema.
entregado

Implementación técnica

Requisitos previos

Clave API de 1MSG · Cómo obtener la clave API
Cuenta de WhatsApp Business · Cómo conectar WABA
Ventana de sesión de 24 horas abierta · Cómo funciona la ventana de 24 horas
Opt-in del cliente · Cómo gestionar el consentimiento
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.

200 OKRespuesta

{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}

sent
Aceptado para envío — aún no en el teléfono del cliente
id
Guárdalo; los callbacks de entrega y hookInfo se basan en él

Estados de entrega y webhooks →

Errores frecuentes

Estado	Respuesta de la API	Causa	Solución
200	Message was not sent: provide chatId, phone, bsuid, or username	Ningún destinatario que el canal pudiera resolver.	Envía un solo destinatario: phone (código de país y número, solo dígitos), chatId (por ejemplo [email protected]) o bsuid.
401	token is required	La petición no incluye el token.	Agrega el token del canal como parámetro token en la URL: https://api.1msg.io/{channelId}/{method}?token=…
429	too many requests. please try later	El canal superó su límite de envío.	Encola los mensajes de tu lado y reintenta con backoff exponencial.