Scopes y acceso por canal
Los nueve scopes del chat y la concesión por canal: las dos puertas que deciden qué puede hacer tu aplicación y en qué canales.
Actualizado el . 4 min de lectura
Incluido en todos los planes. Ver precios
Lo que tu aplicación puede hacer en el Chat depende de dos controles que se cumplen a la vez. Los scopes autorizan la acción (publicar, leer, crear canales...). La concesión de acceso a un canal autoriza el lugar: en qué canales puede hacerlo. Con solo uno de los dos no basta.
Puerta 1: los scopes
Un scope es un permiso de la aplicación, no de una persona. El chat tiene nueve. Asigna solo los que tu aplicación necesite.
| Scope | Nombre en la ficha | Qué autoriza |
|---|---|---|
chat:messages:send | Escribir mensajes | Publicar mensajes como la aplicación. |
chat:channels:view | Ver los canales | Listar los canales concedidos, su detalle y sus miembros. |
chat:messages:view | Leer los mensajes del canal | Leer y buscar los mensajes visibles de los canales concedidos. |
chat:events:subscribe | Recibir avisos de novedades del chat | Recibir webhooks de los canales concedidos. |
chat:channels:create | Crear canales | Crear canales nuevos. |
chat:channels:manage | Crear y organizar canales | Editar y archivar los canales concedidos. |
chat:members:manage | Gestionar los miembros de los canales | Añadir y retirar miembros de los canales concedidos. |
chat:agents:view | Ver los agentes de IA del canal | Consultar los agentes que ha creado la propia aplicación. |
chat:agents:manage:external | Gestionar agentes de IA (capacidad máxima) | Proponer y configurar agentes de IA. Ver Gestionar agentes de IA. |
Se asignan en la pestaña «Permisos» de la configuración de la aplicación. No hay un interruptor aparte para activar el chat: en cuanto la aplicación tiene algún scope chat:*, queda habilitada en la plataforma de chat, y si se le quitan todos, deja de estarlo.
Los dos scopes de agentes necesitan que el plan incluya la capacidad «Agentes de canal», y chat:agents:manage:external solo lo puede asignar un Super Administrador: no entra en ningún paquete de scopes.
Cada acción exige su propio scope: los de lectura (chat:channels:view, chat:messages:view) y el de avisos (chat:events:subscribe) no permiten publicar ni cambiar nada. Sin el scope de la acción, la respuesta es 403 INSUFFICIENT_SCOPE.
Puerta 2: la concesión de acceso al canal
Además del scope, tu aplicación necesita una concesión activa en cada canal donde vaya a actuar. No llega sola al crear la aplicación: la da una persona desde el Chat, en el panel del canal, pestaña «Apps», con «Dar acceso a una app».
Puede darla quien sea propietario o administrador de ese canal y tenga el permiso «Gestionar apps en canales» (CHAT_APPS_MANAGE), o un Super Administrador de la organización.
Al conceder el acceso, esa persona elige qué puede hacer la aplicación en el canal:
| Capacidad en el panel | Qué permite |
|---|---|
| Leer los mensajes del canal | Leer el historial. |
| Escribir mensajes | Publicar. |
| Crear y organizar canales | Crear canales y editar o archivar este. |
| Gestionar miembros | Añadir y quitar personas. |
| Gestionar agentes de IA en nombre de tu equipo | Proponer agentes de IA (solo si la aplicación tiene ese scope). |
La concesión nunca va más allá de los scopes de la aplicación ni de lo que puede hacer la persona que concede: solo se ofrecen las capacidades que esa persona tiene hoy.
Al recibir el acceso, la aplicación pasa a ser miembro del canal, con su identidad de aplicación.
Las acciones de gobierno van en nombre de quien concedió
Cuando tu aplicación crea, edita o archiva un canal o gestiona sus miembros, actúa en nombre de la persona que le dio acceso, y UTILIA OS comprueba en cada llamada que esa persona conserva hoy el permiso correspondiente. Si lo pierde, tu aplicación deja de poder hacerlo en ese mismo momento. Detalle en Crear canales y gestionar miembros.
Estados de la concesión
Quien administra el canal puede pausar el acceso de tu aplicación o retirarlo, desde la fila de la aplicación en la pestaña «Apps».
Estados del acceso de una aplicación a un canal
Activa
ACTIVE
La aplicación hace lo que incluya la concesión.Se llega desde Activa cuando: «Retirar acceso»
Revocada
REVOKED
Deja de ser miembro del canal y desaparece de la lista.
Se llega desde Activa cuando: «Pausar»
En pausa
SUSPENDED
No puede hacer nada mientras siga en pausa.
Otras transiciones
- En pausa pasa a Activa: «Reanudar» la vuelve a activar, con las capacidades revalidadas.
- En pausa pasa a Revocada: «Retirar acceso» también funciona en pausa.
- Revocada pasa a Activa: Volver a «Dar acceso a una app» crea de nuevo una concesión activa.
Sin concesión activa, publicar responde 403 APP_NOT_AUTHORIZED_IN_CHANNEL y leer responde 404 CHANNEL_NOT_FOUND.
Dónde puede actuar
Solo en canales y grupos. Nunca en conversaciones directas entre personas ni en las del portal del cliente: publicar en uno de ellos responde 403 APP_NOT_AUTHORIZED_IN_CHANNEL. Y si el canal no existe o es de otra organización, la respuesta es 404 CHANNEL_NOT_FOUND, sin decir cuál de las dos cosas pasa.
Siguiente paso
Con el scope chat:messages:send y una concesión que incluya «Escribir mensajes», tu aplicación ya puede publicar su primer mensaje. Cómo se ve todo esto desde el lado de quien administra el canal está en Añadir un agente de IA a un canal y en la guía del Chat.