Documentación del Servicio de Reservas
Tabla de contenido
ninguno
Descripción general
El Servicio de Reservas es un sistema integral de gestión de citas que te permite:
- Crear y administrar servicios de reserva para tu negocio
- Programar citas con recordatorios automáticos
- Hacer seguimiento del estado de las reservas durante todo su ciclo de vida
- Enviar seguimientos automáticos después de las citas
- Integrarlo con los flujos de trabajo de tu chatbot
Importante: Los servicios de reserva se comparten entre todos los bots de tu espacio de trabajo, con un límite máximo de 20 servicios de reserva.
Funciones principales
1. Servicios de reserva
- Define diferentes tipos de citas (consultas, reuniones, servicios, etc.)
- Establece la duración predeterminada para cada tipo de servicio
- Configura identificadores personalizados del servicio (Service UID)
- Activa o desactiva servicios según sea necesario
2. Recordatorios automáticos
- Configura hasta 5 secuencias de recordatorios por servicio
- Configura el momento del recordatorio (días, horas, minutos antes de la cita)
- Personaliza los mensajes de recordatorio
- Activación automática de recordatorios según la hora programada
3. Seguimientos automáticos
- Configura hasta 5 secuencias de seguimiento por servicio
- Envía seguimientos después de citas completadas o ausencias
- Configura el momento del seguimiento (días, horas, minutos después de la cita)
- Personaliza los mensajes de seguimiento
4. Gestión del estado de las reservas
Haz seguimiento de las reservas durante todo su ciclo de vida:
- Pending: Estado inicial de la reserva
- Confirmed: La reserva ha sido confirmada
- In Progress: La reunión/cita ha comenzado
- Completed: Completada exitosamente
- Cancelled: La reserva fue cancelada
- No Show: El cliente no asistió
- Inactive: El servicio ya no está activo
5. Información de la reserva
- Horas de inicio y fin
- Duración (en minutos)
- Detalles de la ubicación
- Seguimiento de origen
- Metadatos personalizados
- Sistema de calificación (0-5 estrellas)
- Motivos de cancelación/reprogramación
- Registros completos de auditoría
Primeros pasos
Requisitos previos
- Cuenta de espacio de trabajo con el complemento Ticket/Lists/Bookings habilitado
- Acceso a la gestión del servicio de reservas
- Comprensión básica de la zona horaria de tu espacio de trabajo
Pasos de configuración inicial
Navega a Servicios de Reserva
- Ve a la configuración de tu espacio de trabajo
- Selecciona "Booking Services" en el menú
Crea tu primer servicio de reserva
- Haz clic en el botón "+ Booking Service"
- Completa la información requerida
- Configura recordatorios y seguimientos
- Guarda tu servicio
Integración con el chatbot
- Usa el Service UID para hacer referencia al servicio en los flujos de tu bot
- Configura disparadores para eventos de reserva
- Configura respuestas automáticas
Cómo funciona
Arquitectura del sistema
El sistema de reservas opera con base en trabajos programados:
1. Creación de reserva: Cuando se crea una reserva, el sistema genera automáticamente programaciones de recordatorios y seguimientos según tu configuración.
Procesamiento de recordatorios:
- Se ejecuta cada minuto
- Verifica recordatorios pendientes dentro de una ventana de 2 horas
- Envía recordatorios y actualiza el estado a "sent"
Eventos de reunión:
- Inicio de reunión: Se activa automáticamente cuando se alcanza la hora de inicio
- Fin de reunión: Se activa automáticamente cuando se alcanza la hora de finalización
Procesamiento de seguimientos:
- Se programa después de que la reserva se complete o se marque como ausencia
- Se ejecuta con la misma programación que los recordatorios
- Solo envía mensajes para reservas completadas o con ausencia
Configuración de servicios de reserva
Paso 1: Crear un servicio de reserva
Campos requeridos:
- Name: Nombre para mostrar de tu servicio (máx. 100 caracteres)
- Service UID: Identificador único con caracteres alfanuméricos (máx. 50 caracteres)
No se puede cambiar después de la creación
- Ejemplo: consultation_30min, demo_call, support_session
Description: Descripción detallada (máx. 1,000 caracteres)
Default Duration: Duración en minutos (0-1000)
Status: Active o Inactive
Paso 2: Configurar recordatorios
Para cada recordatorio:
1. Sequence Number: Se asigna automáticamente (1-5)
2. Title: Descripción corta (máx. 50 caracteres)
3. Description: Mensaje detallado (máx. 500 caracteres)
Timing: Define cuándo enviar el recordatorio
- Días antes de la hora de inicio
- Horas antes de la hora de inicio
- Minutos antes de la hora de inicio
4. Status: Active o Inactive
Ejemplo de configuración de recordatorio:
Paso 3: Configurar seguimientos
Para cada seguimiento:
1. Sequence Number: Se asigna automáticamente (1-5)
2. Title: Descripción corta (máx. 50 caracteres)
3. Description: Mensaje detallado (máx. 500 caracteres)
Timing: Define cuándo enviar el seguimiento
- Días después de la hora de finalización
- Horas después de la hora de finalización
- Minutos después de la hora de finalización
4. Status: Active o Inactive
Ejemplo de configuración de seguimiento:
Gestión de reservas
Crear una reserva
Información requerida:
- Service UID o Booking Service ID
- Hora de inicio (en la zona horaria del espacio de trabajo)
- Estado inicial (Pending o Confirmed)
Información opcional:
- Duración personalizada (anula el valor predeterminado)
- Ubicación (máx. 1,000 caracteres)
- Source (máx. 100 caracteres)
- Metadata (máx. 5,000 caracteres)
- Notes (máx. 1,000 caracteres)
Notas importantes:
- La hora de inicio debe estar en el futuro
- Los recordatorios se programan automáticamente
Acciones de la reserva
#### 1. Confirmar reserva
- Cambia el estado de Pending a Confirmed
- Solo disponible para reservas pendientes
- Despacha el evento BOOKING_CONFIRMED
#### 2. Reprogramar reserva
- Actualiza la hora de inicio, la hora de finalización y la duración
- Puede cambiar el estado a Pending o Confirmed
- Conserva los recordatorios ya enviados
- Reprograma los recordatorios restantes
- Requiere motivo de reprogramación (máx. 500 caracteres)
Restricciones:
- No se pueden reprogramar reservas en progreso
- No se pueden reprogramar reservas en estado final (cancelled, completed, no-show)
#### 3. Cancelar reserva
- Cambia el estado a Cancelled
- Cancela todos los recordatorios y seguimientos pendientes
- Requiere motivo de cancelación (máx. 500 caracteres)
- No se pueden cancelar reservas en estado final
#### 4. Marcar como completada
- Cambia el estado a Completed
- Omite cualquier recordatorio no enviado
- Programa mensajes de seguimiento
- No se pueden completar reservas en estado final
#### 5. Marcar como ausencia
- Cambia el estado a No Show
- Omite cualquier recordatorio no enviado
- Programa mensajes de seguimiento (igual que completed)
- No se pueden marcar reservas en estado final como no-show
#### 6. Actualizar calificación
- Establece una calificación de 0 a 5 estrellas
- Puede actualizarse en cualquier momento
- Registra el cambio de calificación
#### 7. Actualizar detalles de la reserva
- Modifica la ubicación, el origen o los metadatos
- No afecta el estado ni la programación
#### 8. Eliminar reserva
- Elimina permanentemente la reserva
- Borra todos los recordatorios, seguimientos y registros asociados
- No se puede deshacer
Recordatorios y seguimientos
Comportamiento de los recordatorios
Programación:
- Se crean cuando se crea la reserva
- Se calculan como: start_time - (days + hours + minutes)
- El estado se establece en "pending" si está en el futuro, "skipped" si está en el pasado
Envío:
- Los recordatorios se envían cuando se alcanza la hora programada
- El estado cambia a "sent"
- Registra la marca de tiempo de envío
- Activa el evento REMINDER_SENDING
Estados:
- Pending: En espera de ser enviado
- Sent: Entregado correctamente
- Skipped: No enviado (el tiempo pasó o la reserva fue cancelada)
- Cancelled: La reserva fue cancelada
Reprogramación:
- Solo se reprograman los recordatorios no enviados
- Los recordatorios enviados se conservan
- Se calculan nuevas horas programadas
Comportamiento de los seguimientos
Programación:
- Solo se crean cuando la reserva se marca como Completed o No Show
- Se calculan como: end_time + (days + hours + minutes)
- El estado se establece en "pending" si está en el futuro, "skipped" si está en el pasado
Envío:
- Los seguimientos se envían cuando se alcanza la hora programada
- El estado cambia a "sent"
- Registra la marca de tiempo de envío
- Activa el evento FOLLOWUP_SENDING
Importante:
- Los seguimientos NO se crean al momento de la reserva
- Solo se programan después de completarse o marcarse como ausencia
- Las reservas canceladas no reciben seguimientos
Ciclo de vida de la reserva
Transiciones de estado
Flujo de eventos
1. BOOKING_CREATED: Creación inicial de la reserva
2. BOOKING_CONFIRMED: Reserva confirmada por el usuario o el sistema
3. REMINDER_SENDING: Cada recordatorio a medida que se envía
4. MEETING_STARTED: Se alcanzó la hora de inicio
5. MEETING_ENDED: Se alcanzó la hora de finalización (completa automáticamente la reserva)
6. BOOKING_COMPLETED: Completada manual o automáticamente
7. BOOKING_NO_SHOW: Marcada como ausencia
8. FOLLOWUP_SENDING: Cada seguimiento a medida que se envía
9. UPDATE_RATING: Calificación actualizada
10. BOOKING_RESCHEDULED: La hora de la reserva cambió
11. BOOKING_CANCELLED: Reserva cancelada
Cambios automáticos de estado
- Pending/Confirmed → In Progress: Cuando se alcanza start_time
- In Progress → Completed: Cuando se alcanza end_time (mediante proceso automático)
Acciones de API
Gestión de servicios
- list_booking_services: Obtener todos los servicios de reserva
- get_booking_service: Obtener detalles de un servicio específico
- list_booking_service_reminders: Obtener recordatorios de un servicio
- list_booking_service_followups: Obtener seguimientos de un servicio
Gestión de reservas
- list_bookings: Obtener reservas (filtradas por usuario, servicio, estado)
- get_booking: Obtener detalles de una reserva específica
- create_booking: Crear una nueva reserva
- confirm_booking: Confirmar una reserva pendiente
- reschedule_booking: Cambiar la hora de la reserva
- cancel_booking: Cancelar una reserva
- mark_booking_completed: Marcar como completada
- mark_booking_no_show: Marcar como ausencia
- update_booking_rating: Actualizar calificación
Parámetros
Parámetros comunes:
- bot_user_ns: Identificador del usuario del bot (para pruebas)
- service_uid: Identificador único del servicio
- booking_id: ID de reserva específica
Creación de reservas:
- start_time: Formato ISO 8601 UTC (p. ej., "2020-01-02T12:30:00Z")
- duration: Minutos (opcional, usa el valor predeterminado si no se especifica)
- pending_or_confirmed: Estado inicial
- location: Ubicación de la cita
- source: Origen de la reserva
- metadata: Datos personalizados (cadena JSON)
- notes: Notas adicionales
Actualizaciones de estado:
- reschedule_reason: Motivo de la reprogramación (máx. 500 caracteres)
- cancel_reason: Motivo de la cancelación (máx. 500 caracteres)
- rating: Número entre 0-5
Diagramas de secuencia
Flujo de creación de reserva
Flujo de procesamiento de recordatorios
Flujo de finalización de reserva
Automatización de inicio/fin de reunión
Flujo de reprogramación
Mejores prácticas
1. Configuración del servicio
- Usa nombres de servicio claros y descriptivos
- Crea Service UID únicos que sean fáciles de referenciar
- Establece duraciones predeterminadas realistas
- Prueba el tiempo de recordatorios y seguimientos antes de salir a producción
2. Estrategia de recordatorios
- No envíes demasiados recordatorios (por lo general, 2-3 son suficientes)
- Espacia los recordatorios adecuadamente (p. ej., 1 día antes, 1 hora antes)
- Haz que los mensajes de recordatorio sean claros y accionables
- Incluye detalles relevantes de la reserva en los recordatorios
3. Estrategia de seguimiento
- Envía un seguimiento inmediato para solicitar comentarios (2-4 horas después)
- Envía una solicitud de encuesta 24 horas después de la cita
- Mantén los mensajes de seguimiento breves y enfocados
- Incluye siempre opciones para dejar de recibirlos
4. Gestión de reservas
- Proporciona siempre motivos de cancelación para analítica
- Usa el campo de notas para capturar contexto importante
- Actualiza las calificaciones para dar seguimiento a la calidad del servicio
- Revisa regularmente los registros de reservas
5. Pruebas
- Prueba el ciclo de vida completo de la reserva antes del lanzamiento
- Verifica el tiempo de los recordatorios en tu zona horaria
- Prueba escenarios de reprogramación
- Valida que los disparadores de eventos se activen correctamente
Solución de problemas
Problemas comunes
Los recordatorios no se envían:
- Verifica que el recordatorio esté en "Active"
- Verifica que la hora programada esté en el futuro
- Confirma que el servicio de reserva esté activo
- Verifica que el estado de la reserva no esté en estado final
Los seguimientos no se envían:
- Los seguimientos solo se envían después de completed o no-show
- Verifica que el seguimiento esté en "Active"
- Verifica que la reserva se haya completado/marcado como no-show (no cancelada)
- Confirma que la hora programada sea correcta
No se puede reprogramar:
- Asegúrate de que la reserva no esté en estado final
- Verifica que la reserva no esté actualmente en progreso
- Comprueba que el servicio siga activo
Problemas de zona horaria:
- Todas las horas se almacenan en UTC
- Las horas mostradas se convierten a la zona horaria del espacio de trabajo
- Verifica que la configuración de la zona horaria del espacio de trabajo sea correcta
Límites y restricciones
- Máximo de Booking Services: 20 por espacio de trabajo
- Máximo de recordatorios: 5 por servicio
- Máximo de seguimientos: 5 por servicio
- Límites de campos:
Name: 100 caracteres
- Service UID: 50 caracteres
- Description: 1,000 caracteres
- Reminder/Follow-up Title: 50 caracteres
- Reminder/Follow-up Description: 500 caracteres
- Reschedule Reason: 500 caracteres
- Cancellation Reason: 500 caracteres
- Location: 1,000 caracteres
- Source: 100 caracteres
- Metadata: 5,000 caracteres
- Notes: 1,000 caracteres