Esta guía conecta el calendario de turnos de Clínica del Sol para que el agente de turnos consulte la disponibilidad y reserve. Sirve igual para Gmail, Drive y Sheets en Google, y para el calendario, el correo y OneDrive de Outlook en Microsoft. Cómo una API se vuelve herramientas del agente y cómo se cuidan las credenciales está en el capítulo Herramientas e integraciones.
Los pasos del lado de Google y Microsoft siguen sus consolas al momento de escribir esta guía. Lo que dice del lado de la plataforma está verificado contra el código.
Antes de empezar
- La app OAuth la creás vos. La plataforma no trae una app propia: hace falta un cliente OAuth en Google Cloud o en Microsoft Entra, de la clínica o de la agencia.
- Una cuenta conectada por tenant y por proveedor. El agente actúa como la cuenta que dio el permiso —por ejemplo, la cuenta de turnos de la clínica—, no como la persona que conversa. Todo lo que esa cuenta puede ver o modificar, el agente también.
- El permiso se pide al activar cada servicio, no al instalar. Instalar solo guarda los datos de la app.
- Las pantallas de este flujo todavía están en inglés, aunque el admin esté en español.
1. La URL de redirección
En Integraciones, elegí Google Workspace o Microsoft 365 e instalalo. El primer paso, Credentials, muestra un recuadro Redirect URI con la URL que hay que registrar en el proveedor. En la instalación de Synaptic Links es:
https://ai.synapticlinks.com.ar/admin-api/admin/oauth2/callback
Copiala de la pantalla: tiene que coincidir carácter por carácter con la que registres.
2. Crear la app en el proveedor
- En Google Cloud Console, creá un proyecto y habilitá las APIs que vayas a usar: Calendar, Gmail, Drive, Sheets.
- Configurá la pantalla de consentimiento:
- Interna, si la cuenta que va a conectar es de Google Workspace de la misma organización. Es lo más simple.
- Externa, en cualquier otro caso. Mientras esté en modo de prueba, hay que agregar la cuenta como usuario de prueba, y el permiso vence a los 7 días: el agente deja de poder usar Google y hay que reautorizar.
- Creá un cliente OAuth de tipo aplicación web y agregá la URL de redirección del paso 1.
- Copiá el Client ID y el Client Secret.
Gmail y Drive piden permisos que Google considera restringidos, y el calendario, sensibles. Para usar una app externa sin el límite de 7 días hay que pasar la verificación de Google.
Microsoft
- En Microsoft Entra, App registrations → New registration.
- Elegí que acepte cuentas de cualquier directorio organizacional y cuentas personales. La plataforma usa los puntos de autorización comunes de Microsoft, y una app restringida a un solo directorio puede fallar.
- Agregá la URL de redirección del paso 1, de tipo Web.
- En Certificates & secrets, creá un secreto y copiá su Value. El secreto vence: anotá la fecha.
- En API permissions, agregá los permisos delegados de Microsoft Graph que correspondan:
Calendars.ReadWritepara el calendario,Mail.ReadWriteyMail.Sendpara el correo,Files.ReadWrite.Allpara OneDrive. - Si la organización de la clínica no deja que los usuarios den permisos por su cuenta, un administrador tiene que dar el consentimiento.
3. Cargar la app en la plataforma
En el paso Credentials del asistente de instalación:
| Campo | Qué va |
|---|---|
| Client ID | El ID del cliente OAuth |
| Client Secret | El secreto, que se guarda cifrado |
El recuadro Required scopes muestra solo los permisos básicos de identificación. Los de cada servicio se agregan más adelante, cuando lo actives.
Connect & Authorize termina la instalación, pero todavía no pide permiso: te lleva al detalle de la integración.
4. Activar servicios y dar el permiso
En el detalle de la integración, la tarjeta Capabilities tiene un interruptor por servicio: Calendar, Gmail, Drive y Sheets, o Outlook Calendar, Outlook Mail y OneDrive.
- Activá el servicio, por ejemplo Calendar.
- Se abre Additional Authorization Required, con los permisos nuevos. Elegí Authorize.
- Iniciá sesión en Google o Microsoft con la cuenta que va a usar el agente y aceptá.
- Volvés al admin con el mensaje "Conexión OAuth2 establecida exitosamente". La pantalla abre la fuente de herramientas que se creó, no el detalle de la integración.
Si cancelás el permiso, el servicio queda activado pero en Needs Authorization, con un botón Authorize para retomarlo.
Cada servicio que activás después vuelve a pedir permiso, sumando los nuevos.
5. Lo que recibe el agente
Cada servicio activado se convierte en una fuente de herramientas, por ejemplo Google Calendar (Google Workspace), con un grupo de operaciones recomendadas activadas:
| Servicio | Operaciones activadas |
|---|---|
| Google Calendar | Listar calendarios y eventos, crear, modificar y borrar eventos, consultar disponibilidad |
| Gmail | Leer, buscar, enviar y etiquetar mensajes e hilos |
| Google Drive | Listar, leer, crear, actualizar y exportar archivos |
| Google Sheets | Leer, crear y actualizar planillas y valores |
| Outlook Calendar | Listar calendarios y eventos, crear, modificar y borrar eventos, buscar horarios |
| Outlook Mail | Leer, enviar, responder y crear borradores |
| OneDrive | Listar, buscar, leer y subir archivos y carpetas |
Desde View Source se pueden activar o desactivar operaciones. Para que el agente las use, hay que asignar la fuente a su paso de herramientas (capítulo 5).
Ninguna operación pide aprobación por sí sola. Si el agente no debe borrar eventos o mandar correos sin que alguien lo confirme, desactivá esas operaciones o agregá un paso de aprobación antes (capítulo 3).
Cuando hay que reautorizar
El acceso se renueva solo mientras el proveedor lo permita. Si Google o Microsoft lo rechazan —se cambió la contraseña, se revocó el permiso, venció el secreto de Microsoft o pasaron los 7 días de una app de Google en prueba—, la plataforma avisa a propietarios y administradores, en el admin y por correo, con el asunto "Una conexión de Clínica del Sol necesita reautorización".
Para reautorizar:
- En el detalle de la integración, en la tarjeta Capabilities, entrá en View Source del servicio activado más recientemente.
- Elegí Re-autorizar e iniciá sesión con la misma cuenta.
Conviene usar la fuente más reciente porque cada fuente recuerda los permisos que existían cuando se creó: reautorizar desde una más vieja puede pedir menos permisos de los que hacen falta. El detalle de la integración puede sugerir el botón Reconnect, pero en estas integraciones no pide un permiso nuevo: usá el camino de arriba.
Desconectar
Disconnect borra las fuentes de herramientas y deja la integración desconectada. No revoca el permiso en Google ni en Microsoft: para cortar el acceso del todo, quitá la app desde la cuenta conectada (en Google, la configuración de seguridad de la cuenta; en Microsoft, las aplicaciones con permiso).
Cuando no funciona
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Google o Microsoft dicen que la URL de redirección no coincide | La URL registrada no es exactamente la de la pantalla | Copiala de nuevo desde el paso Credentials |
| Después de instalar no se pidió ningún permiso | Es el comportamiento esperado | Activá un servicio en Capabilities |
| Google dice que la app no está verificada o que la cuenta no tiene acceso | Pantalla externa en modo de prueba | Agregá la cuenta como usuario de prueba |
| Funcionaba y a la semana dejó de funcionar (Google) | App externa en modo de prueba: el permiso vence a los 7 días | Reautorizá, o verificá la app en Google |
| Dejó de funcionar (Microsoft) | Venció el secreto de la app | Creá un secreto nuevo, cargalo y reautorizá |
| Microsoft pide un administrador | La organización no deja dar permisos a los usuarios | Un administrador da el consentimiento en Entra |
| El servicio sigue en Needs Authorization después de aceptar | Se canceló el permiso o no se otorgaron todos | Volvé a Authorize y aceptá todos los permisos |
Dónde termina
- Una cuenta por proveedor y por tenant. El agente no actúa como cada usuario.
- Las pantallas de este flujo están en inglés.
- El recuadro de permisos del instalador muestra solo los básicos, no los de cada servicio.
- No hay prueba de conexión: se comprueba activando un servicio y usándolo.
- Reautorizar no es directo: se hace desde la fuente, no desde el detalle de la integración.
- Desconectar no revoca el permiso en el proveedor.
- En Microsoft, los puntos de autorización son fijos (cuentas de cualquier organización y personales).
- Las operaciones de escritura no piden aprobación por defecto.
Para revisar
- La URL de redirección registrada es exactamente la de la pantalla.
- La cuenta que dio el permiso es la que el agente debe usar, y no tiene más acceso del necesario.
- Están activados solo los servicios y operaciones que el agente necesita.
- Borrar eventos y mandar correos pasa por una aprobación, o está desactivado.
- En Google, la app es interna o está verificada; en Microsoft, está anotado cuándo vence el secreto.
- Propietarios y administradores reciben los avisos de reautorización.