Reservas con Cal.com

Conecta tu calendario#

Abre Agente → Acciones → Cal.com. Introduce una clave de API de Cal.com que empiece por cal_, el ID numérico positivo del tipo de evento y una zona horaria IANA, como Asia/Seoul. Elige Guardar conexión. Cada agente tiene su propia conexión. La clave se cifra en el servidor; el panel solo muestra sus últimos cuatro caracteres. Si actualizas una conexión existente, deja la clave en blanco para conservarla.

Elige Probar conexión para leer hasta tres horarios próximos de los siguientes siete días con los ajustes introducidos. Esta prueba no guarda la conexión ni crea ninguna reserva. Que no aparezcan horarios puede significar simplemente que el tipo de evento no tiene disponibilidad en ese periodo. Si la prueba falla, revisa en Cal.com la clave, el tipo de evento y el horario. Si eliminas la conexión, el agente deja de crear nuevas reservas en Cal.com, pero no cancela las reservas existentes.

Los pagos quedan fuera del alcance. Google Calendar es una opción independiente que todavía no está disponible de forma general.

De los horarios a la reserva#

1. El agente llama a find_slots para obtener disponibilidad futura real. Muestra hasta ocho horarios en la zona horaria configurada. El rango predeterminado va desde hoy hasta siete días después; el intervalo máximo de fechas es de 14 días. Si solo hay un horario disponible, se muestra solo.
2. El cliente elige un horario y proporciona su nombre, su correo electrónico y, opcionalmente, una nota. El agente vuelve a comprobar que el horario sigue libre y que se ofreció en esta conversación. Las ofertas de horarios caducan a los 15 minutos.
3. Una tarjeta de confirmación muestra la fecha, la hora, la zona horaria y los datos del asistente. El cliente debe pulsar Confirmar. Un mensaje en el chat o la selección de un horario, por sí solos, no reservan nada. La propuesta caduca a los 15 minutos y no bloquea el horario.
4. Solo después de la confirmación, el adaptador solicita la reserva a Cal.com. Un resultado accepted de Cal.com pasa a done, con el UID de la reserva como referencia. pending o awaiting_host permanece como pendiente; un rechazo o una cancelación pasa a fallido.

En los canales de mensajería, las propuestas de reserva solo funcionan en chats privados. El ensayo no llama a Cal.com ni crea ninguna reserva. Sin una conexión con Cal.com, sigue disponible el flujo actual de solicitud de reserva, que no demuestra que se haya reservado un hueco en el calendario. Si cambias la clave, el tipo de evento o la zona horaria, el destino de ejecución de la propuesta deja de ser válido, así que empieza de nuevo después de cambiar la conexión.

Si un horario ya está ocupado o el resultado es incierto#

Otro cliente puede ocupar un horario antes de que termine la confirmación. Si el horario ya no está libre, el agente informa de que no está disponible; si Cal.com lo rechaza durante la creación, el recibo muestra un fallo. Pide horarios nuevos y confirma una propuesta nueva. El recibo de fallo no adjunta automáticamente nuevas opciones.

Un tiempo de espera agotado en la red no demuestra ni un fallo ni un éxito. El recibo muestra un resultado desconocido mientras el servicio vuelve a comprobarlo. El endpoint de creación de Cal.com no tiene un contrato documentado de clave de idempotencia, por lo que el adaptador guarda el ID de ejecución en metadata.maf_run y busca esa reserva en todos los estados y páginas antes de reintentar la creación. Una búsqueda incompleta nunca permite enviar otra solicitud de creación. Esto reduce el riesgo de duplicados, pero no es una garantía de ejecución exactamente una vez respaldada por el proveedor. Antes de hacer otra reserva tras agotar los reintentos, comprueba Cal.com.

La aprobación del anfitrión en Cal.com es independiente de la aprobación del propietario en las acciones de cambio personalizadas. Esta integración no actualiza automáticamente una reserva pendiente de Cal.com; comprueba su estado final en Cal.com. El widget web puede consultar periódicamente el recibo de ejecución almacenado, y los canales privados compatibles reciben los recibos diferidos según sus ventanas de servicio. Consulta la entrega de recibos.

Versiones de la API y comprobaciones previas al lanzamiento#

El adaptador envía autenticación Bearer y estos valores de cal-api-version específicos de cada endpoint, verificados con la documentación oficial el 2026-10-13:

Antes de usarlo con clientes, prueba una reserva controlada, verifica el UID en Cal.com, intenta reservar un horario ocupado y comprueba los recibos en cada canal previsto. Una prueba de conexión correcta solo demuestra una lectura de horarios, no una reserva real ni que todo esté listo para producción.