> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agendar y gestionar citas (Cal.com) > El agente de voz consulta disponibilidad real, aparta la cita, la cancela y la reagenda durante la misma llamada. Con esta herramienta el agente aparta la cita durante la llamada: el interesado cuelga con el horario ya puesto en la agenda real del negocio y con el correo de confirmación en camino. No hay callback pendiente, ni enlace que abrir, ni captura a mano después. ## Qué hace el agente durante la llamada | Capacidad | Qué significa en la conversación | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | Consultar disponibilidad | El cliente pregunta «¿qué horarios tienen?» y el agente lee los huecos libres reales, en ese momento. | | Agendar | El cliente elige un horario y el agente lo aparta con su nombre, su correo y el motivo de la cita. | | Cancelar | El cliente pide cancelar; la cita queda cancelada y se dispara el aviso. | | Reagendar | El agente consulta de nuevo la disponibilidad, propone horarios reales y mueve la cita. | **Se instala una sola herramienta y vienen las cuatro.** En el catálogo hay una única tarjeta que instalar, «Agendar y gestionar citas (Cal.com)» (identificador `book_appointment_cal`). Consultar disponibilidad, cancelar y reagendar **no se configuran aparte**: se derivan de esa instalación y reusan su misma credencial y su mismo tipo de cita. ### El agente pide los datos, no los inventa Antes de apartar cualquier horario, el agente se asegura de tener tres datos dichos por el cliente en esa conversación: **nombre real**, **correo electrónico** —que confirma repitiéndolo, y que escribe bien aunque se lo dicten hablando: «arroba» pasa a `@` y «punto» a `.`, sin espacios y en minúsculas— y el **motivo de la cita**, que queda en las notas. Si falta alguno, lo pide de forma natural y no agenda hasta tenerlo. ### El agente no confirma lo que no ocurrió Cuando cancela o mueve una cita, la plataforma le dice exactamente qué pasó, y el agente sólo confirma si de verdad pasó: * Si la cita quedó cancelada o movida, lo confirma. * Si encuentra **varias citas** con el mismo correo, no adivina: pregunta cuál es. * Si **no encuentra** la cita, no dice que la canceló: verifica el correo o registra la solicitud para que el equipo la atienda. * Si el calendario falla, tampoco confirma: registra la solicitud. ## Configuración La herramienta se instala en el agente, en su pestaña **Herramientas**. El formulario tiene cuatro campos y dos ya vienen resueltos. Es el texto que le dice al agente cuándo y cómo usar la agenda. Viene precargado con la versión probada y **nace bloqueado**. Para editarlo hay que pulsar «Editar» y confirmar en una ventana que advierte del riesgo, marcando la casilla correspondiente. Sólo entonces la etiqueta cambia a «Editable» y aparece un botón «Restablecer» que devuelve el texto original en un clic. El tope son **1024 caracteres**. Para quien integra esto significa dos cosas: funciona de fábrica sin tocar nada, y no se puede romper por descuido. La llave que le presta el calendario al agente. Se genera en Cal.com y empieza siempre con `cal_live_`. La ayuda del campo nombra los menús en inglés, pero **si Cal.com está en español se llaman distinto**, y ahí está el tropiezo más común: * Enlace directo: `app.cal.com/settings/developer/api-keys` * Por menú: rueda de ajustes → **Desarrollador** → **Claves API** → **+ Nuevo** En la ventana «Crear una clave API» hay dos decisiones: * Dejar seleccionada la opción **«Clave API»**, no «Cliente OAuth». * Activar el interruptor **«Nunca caduca»**. Si se deja apagado, Cal.com pone una caducidad de **30 días** por defecto, y ese día el agente deja de poder consultar y apartar citas **sin avisar antes**. Al pulsar «Crear», Cal.com **muestra la llave completa una sola vez**. Hay que copiarla en ese momento. El número que identifica **qué tipo de cita** se va a agendar: una demostración de 30 minutos, una asesoría de una hora. Sólo acepta números. La lista está en `app.cal.com/event-types` —en español aparece en el menú como **«Enlaces»**—, pero **en la lista el número no se ve**: hay que abrir el tipo de cita y entonces aparece al final de la dirección del navegador (`app.cal.com/event-types/6168084`). Se copia sólo el número. Cada instalación apunta a **un** tipo de cita. Si el negocio quiere agendar dos servicios distintos con reglas distintas, son dos configuraciones. Determina en qué zona se interpretan los horarios. Al instalar aparece vacío y, si se deja así, se usa `America/Mexico_City`. **Conviene elegirla siempre de forma explícita.** Para un cliente en Bogotá, Santiago o Buenos Aires, dejarla sin elegir significa citas a la hora equivocada. El agente no pregunta la zona horaria durante la llamada: se define aquí, una sola vez. ### Conectarla por API La instalación equivale a crear una conexión de la tool con el agente. El `eventTypeId` y la `timezone` no son sensibles y viajan en `metadata`; la llave de Cal.com va en `auth` y se guarda en el secreto de la conexión — **la API nunca la devuelve de vuelta**. ```bash theme={null} curl --request POST \ --url "$API_BASE_URL/v1/tools/book_appointment_cal/connections" \ --header "X-API-Key: $API_KEY" \ --header "X-Workspace-Id: $WORKSPACE_ID" \ --header "Content-Type: application/json" \ --data '{ "agentId": "38f62697-0f4b-49bc-8a0c-67256f5af6ff", "metadata": { "connectionConfig": { "eventTypeId": "6168084", "timezone": "America/Mexico_City" } }, "auth": { "type": "api_key", "data": { "calApiKey": "cal_live_xxxxxxxxxxxxxxxx" } } }' ``` Requiere el scope `tools:connections:write`. El `toolId` de la ruta es el identificador del catálogo, no un UUID. Al editar la conexión, la llave **nunca se vuelve a mostrar completa**: se ven sus últimos cuatro caracteres. Se puede cambiar el resto de la configuración sin volver a pegarla; dejando el campo vacío se conserva la guardada. ## Errores de validación del formulario | Situación | Mensaje | | ---------------------------------- | ---------------------------------------------------- | | Sin llave (y sin una guardada) | Ingresa el API Key de Cal.com. | | Sin identificador del tipo de cita | Ingresa el Event Type ID de Cal.com. | | Letras donde van números | El Event Type ID debe ser numérico. | | Descripción demasiado larga | La descripción no puede superar los 1024 caracteres. | ## Los límites, dichos de frente * **Hoy funciona en llamadas de voz.** No está disponible para conversaciones de WhatsApp o chat. * **La llave no se verifica al guardar.** Si se pega mal, la instalación se completa con normalidad y el problema sólo aparece en la primera llamada. Por eso toda instalación se cierra con una llamada de prueba. * **La llave caduca a los 30 días si no se dice lo contrario**, y ese día el agente deja de poder consultar y apartar citas sin avisar. Se resuelve con un clic al crearla, con el interruptor «Nunca caduca». * **El agente no aparta un horario que el calendario no le haya ofrecido en esa misma llamada.** Es una protección deliberada: evita citas encima de otras. * **Para cancelar o mover, el agente parte del correo del cliente.** Busca entre sus citas **futuras** de ese tipo de cita; si hay varias, pregunta cuál. Las citas ya pasadas no se tocan. * **La disponibilidad la manda el calendario del cliente, no la plataforma.** Si su calendario está mal configurado, el agente ofrecerá exactamente eso. Ojo con los bloqueos de día completo: Google Calendar suele marcar vacaciones y días fuera de oficina como *libre*, y entonces no bloquean nada. * **Se habilita por cuenta.** La herramienta se activa para el espacio de trabajo cuando se decide, sin instalar nada ni actualizar la plataforma del cliente. ## Preguntas frecuentes No. El negocio sigue administrando su agenda en Cal.com como hasta ahora. El agente sólo lee lo que ese calendario dice y aparta en él. No. Cal.com se conecta al calendario que el negocio ya usa, y desde ese momento el agente respeta las ocupaciones que haya ahí. En **Aplicaciones → Tienda de aplicaciones → Aplicaciones Calendar** están Google Calendar, Outlook Calendar (Office 365), Apple Calendar, Zoho Calendar, Microsoft Exchange, Lark, Vimcal, y las vías genéricas CalDav e ICS Feed. Con el calendario conectado, los horarios ya ocupados dejan de ofrecerse y las citas que aparta el agente aparecen en el calendario de siempre, no en un sistema aparte. No. El agente aparta la cita durante la llamada y Cal.com manda la confirmación. Lo que sí conviene es revisar el calendario los primeros días, como con cualquier proceso nuevo. El agente no agenda sin correo: sin correo no hay confirmación ni forma de mover la cita después. Insistirá de forma natural; si el cliente se niega, la cita no se aparta. Sí. Basta con que la pida: el agente la localiza por su correo, consulta la nueva disponibilidad y la mueve. La llave se guarda aparte de la configuración y la plataforma nunca la vuelve a mostrar: en pantalla sólo se ven sus últimos cuatro caracteres. Da acceso al tipo de cita configurado, y se puede reemplazar o revocar desde Cal.com en cualquier momento. Ninguno, siempre que la llave se haya creado con «Nunca caduca» activado. Si se dejó el plazo por defecto de 30 días, hay que generar una nueva antes de esa fecha y pegarla en el mismo campo.