# 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. 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` | Editar y archivar 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](https://os.utilia.ai/docs/developers/chat-platform/managed-agents). | 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](https://os.utilia.ai/docs/developers/chat-platform/channel-endpoints). ### 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** 1. **Activa** (`ACTIVE`). La aplicación hace lo que incluya la concesión. - **Revocada** (`REVOKED`). Se llega desde Activa cuando: «Retirar acceso». Deja de ser miembro del canal y desaparece de la lista. 2. **En pausa** (`SUSPENDED`). Se llega desde Activa cuando: «Pausar». No puede hacer nada mientras siga en pausa. Otras transiciones: - En pausa → Activa: «Reanudar» la vuelve a activar, con las capacidades revalidadas. - En pausa → Revocada: «Retirar acceso» también funciona en pausa. - Revocada → 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](https://os.utilia.ai/docs/developers/chat-platform/post-messages). 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](https://os.utilia.ai/docs/guides/chat/ai-agents) y en la guía del [Chat](https://os.utilia.ai/docs/guides/chat/channels).