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:

El id del flow y la etiqueta del CTA se definen en el contrato de integración; reemplaza el id de flow de ejemplo con tu Flow publicado.

Variables y propósito

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

Ejemplo completado

Hola Alex, reserva tu cita:

Cuándo usarlo

• citas de servicio

Valor para el negocio

• Client message or booking intent keeps the WhatsApp session window open
• Backend resolves the customer name and published flow id
• sendFlow delivers the flow CTA with personalised greeting text
• Client completes the Meta Flow form inside WhatsApp
• Booking data returns to CRM or calendar integration via flow completion webhook

Flujo de trabajo

1. Un cliente expresa intención de reservar mientras la sesión está abierta.
2. Tu backend obtiene el nombre del cliente y el id del flow.
3. sendFlow envía el saludo con el CTA Reservar ahora.
4. El cliente completa el formulario del flow y los datos de reserva regresan a tu sistema.
5. El progreso de entrega se reporta de forma asíncrona — típicamente sent, luego delivered (o failed/undelivered).
6. Tu sistema recibe el estado vía webhook (hooks[]) o consulta el estado de entrega y maneja fallos si es necesario.

Implementación técnica

Requisitos previos

• Ventana de sesión de WhatsApp abierta y un id de Meta Flow publicado.
• Canal 1MSG con acceso a sendFlow y un token de flow en el backend.

Ejemplos de código

#!/usr/bin/env node

// === Configuration (replace "___" placeholders) ===
const API_BASE_URL = "https://api.1msg.io"; // production 1MSG API base URL
const CHANNEL_ID = "___";                   // channel ID from 1MSG dashboard
const API_TOKEN = "___";                    // channel JWT token (Bearer)



// === Test data ===
const TEST_PHONE = "___";            // client phone in international format · requires open 24-hour session window
const FLOW_TOKEN = "___";                 // flow token from your backend
const TEST_CUSTOMERNAME = "___";    // {{1}} customer name

function normalizePhone(phone) {
  return String(phone).replace(/\D/g, "");
}

async function sendFlowMessage({ phone, flowToken, customerName }) {
  const url = `${API_BASE_URL}/${CHANNEL_ID}/sendFlow`;
  const requestBody = {
    phone: normalizePhone(phone),
    body: `Hi ${customerName}, book your appointment:`,
    flowId: "1234567890",
    flowToken,
    flowCta: "Book now",
    flowAction: "navigate",
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });

  const raw = await res.text();
  let data;
  try {
    data = JSON.parse(raw);
  } catch {
    data = null;
  }

  if (!res.ok || !data || data.sent !== true) {
    console.error("Send failed.");
    console.error(raw);
    process.exit(1);
  }

  console.log("Message sent to client.");
  return data;
}

if (require.main === module) {
  sendFlowMessage({
    phone: TEST_PHONE,
    flowToken: FLOW_TOKEN,
    customerName: TEST_CUSTOMERNAME,
  }).catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { sendFlowMessage };

Respuesta inmediata de la API (síncrona)

• 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` de la respuesta (valor tipo wamid.…). Úsalo para correlacionar callbacks de entrega o polling.
• La respuesta también puede incluir message y description — solo informativos.

Estado de entrega (asíncrono)

• Registra un webhook (POST …/webhook) para que 1MSG envíe actualizaciones de entrega a tu endpoint HTTPS en un payload `hooks[]` separado (sent, delivered, read, o failed/undelivered cuando aplique).
• Opcionalmente consulta: GET {base}/{channel}/hookInfo?messageId=<id de sendTemplate>.
• En la práctica, la entrega suele completarse en pocos segundos — pero eso no está garantizado por el contrato de la API.

Errores frecuentes

• Ventana de sesión cerrada (sin mensaje del cliente en 24 horas)
• Número de teléfono inválido o no normalizado
• Cuerpo del mensaje / URL de media ausente o inválida
• Fallo de entrega — revisa el webhook de estado y la política de reintentos

Preguntas frecuentes

• ¿Necesito una plantilla? No — este escenario usa un mensaje de sesión dentro de la ventana de atención de 24 horas.
• ¿Cuándo se cierra la ventana de sesión? Si el cliente no escribió ni respondió en 24 horas, sendMessage fallará hasta que una plantilla reabra el chat.
• ¿Cómo verifico la entrega? sent: true solo confirma aceptación. Rastrea la entrega vía webhook hooks[] o polling.
• ¿Qué pasa si no se entrega? Registra el hook failed/undelivered, verifica la ventana de sesión, luego reintenta o usa una plantilla.
• ¿Puedo conectarlo a mi CRM o backend? Sí — dispara la llamada a la API desde tu webhook entrante o motor de flujos.

Recursos relacionados

• Base de conocimiento
• Crear una plantilla
• Enviar una plantilla
• SDK