Microsoft Teams

Conecta un bot de Microsoft Teams para que los chats y canales inicien y continúen sesiones de Beeuni.

Microsoft Teams es un canal: una mención a @ en un chat o canal de Teams inicia una sesión, y el agente responde ahí mismo con el progreso en tiempo real. Sigue las mismas reglas de sesión, identidad y credenciales que Slack; esta página explica lo específico de Teams.

Todos los proyectos pueden conectar Teams. No hay que activar ninguna opción.

Conectar

Hay dos formas, ambas desde la página Conectores → Canales del proyecto:

• Con un clic (administrado). Un administrador del inquilino de Teams hace clic en Agregar a Teams, inicia sesión y da su consentimiento. Beeuni publica automáticamente la aplicación en el catálogo de Teams de tu organización; no hay que crear ni pegar nada. Después, la fila ofrece Agregar a Teams (un enlace directo al cliente de Teams) para que cualquiera pueda agregar el bot a un chat o canal. Cuando Beeuni publique una versión más reciente de la aplicación, consulta Actualizar la aplicación.

• Usar tu propio bot. Haz clic en Usar tu propia aplicación de Microsoft Teams para abrir un asistente de tres pasos: registra un Azure Bot, conéctalo a Beeuni con su id. de aplicación, secreto de cliente e id. de inquilino, y luego descarga el paquete de aplicación generado y cárgalo en Teams. Usa esta opción si administras tu propio registro de bot.

  El orden importa. Beeuni crea el manifiesto a partir del id. de aplicación que proporcionas, así que solo puede generar el paquete después del paso 2. Antes de pedirte cualquier otra cosa, el asistente muestra el punto de conexión de mensajería que debes pegar en Azure.

La CLI ofrece las mismas opciones que el panel:

beeuni channels connect --platform teams      # prints the admin-consent URL
beeuni channels status --platform teams        # tenant, catalog, publish state, app version
beeuni channels disconnect --platform teams

Actualizar la aplicación

Beeuni agrega permisos a su aplicación de Teams con el tiempo. La versión 1.1.0 de la aplicación agregó ChannelMessage.Read.Group, que el agente necesita para leer el hilo de un canal. La versión 1.3.0 agregó ChatMessage.Read.Chat, para que una respuesta en un chat grupal continúe una sesión sin necesidad de una mención. Si un equipo todavía usa la versión 1.0.0, no se permite leer ningún hilo, y el mensaje de rechazo que recibe el agente indica quién debe solucionarlo.

Dos personas actualizan la aplicación, en este orden:

1. Un administrador de Teams publica la actualización. Si el catálogo de tu organización tiene una versión anterior, la página Canales muestra Actualizar la aplicación de Beeuni en Teams, y el botón de la fila de Teams dice Publicar actualización de la aplicación. El administrador hace clic en él e inicia sesión con Microsoft. beeuni channels status --platform teams muestra ambas versiones, y beeuni channels connect --platform teams muestra el enlace para iniciar sesión.
2. El propietario de un equipo actualiza la aplicación en cada equipo donde Teams lo solicite. En Teams, abre el equipo, luego ⋯ → Administrar equipo → Aplicaciones, selecciona Actualizar en la aplicación de Beeuni y acepta. Teams instala las actualizaciones por su cuenta, salvo que agreguen un permiso o una acción de mensaje; en esos casos, debe intervenir el propietario del equipo.

Beeuni registra la versión de la aplicación en cada publicación. Si la aplicación se instaló antes de que Beeuni empezara a registrar versiones, seguirá apareciendo el aviso hasta la próxima publicación.

Chats, canales y menciones

• Chat personal: todos los mensajes llegan al bot.
• Canal de equipo / chat grupal: una publicación nueva requiere una mención a @. Después, una respuesta en una conversación que el bot ya tiene asignada continúa la sesión sin una mención, como sucede en un hilo de Slack. Para eso se necesitan los permisos de la aplicación ChannelMessage.Read.Group (canales) y ChatMessage.Read.Chat (chats grupales), que el administrador del inquilino autoriza al agregar la aplicación. Si la aplicación se agregó antes de que se solicitaran estos permisos, el propietario de un equipo debe actualizarla: consulta Actualizar la aplicación.

Cada conversación de chat o canal tiene su propia sesión. El primer mensaje la crea; los mensajes posteriores la continúan, incluso después de que el entorno aislado se detenga y se reanude. Si un inquilino está conectado a más de un proyecto, aparece un selector de proyecto con el primer mensaje sin asignar, y se recuerda la elección. En un canal, solo aparece para los mensajes que mencionan al bot; y un comando sobre el proyecto, como /models, primero pregunta qué proyecto elegir.

En un canal, cada publicación nueva inicia su propia sesión. Un chat personal o grupal es una sola conversación durante toda su vida, así que conserva una única sesión hasta que envíes /new. Envía un mensaje después (/new summarize today's deploys) para iniciar la nueva sesión con ese mensaje. La sesión anterior permanece en Beeuni, con todo su historial, y el mensaje de confirmación incluye un enlace a ella.

Nombres de conversaciones

Teams envía ids., como 19:…@thread.tacv2;messageid=…. La página Canales y beeuni channels bindings muestran los nombres que la gente ve en Teams:

Un mensaje de canal incluye el id. del equipo, pero no su nombre, así que Beeuni obtiene y guarda los nombres del equipo y del canal desde Teams. Una publicación en el canal General de un equipo recibe un nombre la próxima vez que la página Canales la muestra. Una publicación en otro canal recibe un nombre con su siguiente mensaje. Hasta entonces, aparece como Hilo del canal.

Quién puede unirse a una sesión

Cada conversación tiene una política de acceso, que se configura con /policy en Teams o en la página Canales, donde N canales en la fila de Teams muestra todas las conversaciones:

• abierta (predeterminada): cualquier miembro del proyecto vinculado puede unirse a una sesión iniciada aquí.
• aprobación: el propietario de la sesión recibe una tarjeta para aprobar o rechazar a cada persona nueva.
• propietario: solo puede unirse la persona que inició la sesión.

Con las políticas aprobación y propietario, la sesión tampoco es visible para todo el proyecto en Beeuni: solo para su propietario, las personas aprobadas y los administradores de la cuenta que supervisan las sesiones. Una decisión en una tarjeta de revisión o aprobación reanuda el agente con cualquier política.

Vincular identidades

El remitente vincula su cuenta de Beeuni una sola vez con /login; después, el agente se ejecuta como esa persona, con sus propias credenciales, secretos y aplicaciones conectadas. Si el remitente no tiene una cuenta vinculada o no tiene acceso al proyecto, recibe una tarjeta para conectarse o solicitar acceso en lugar de iniciar una sesión.

El enlace para iniciar sesión solo aparece donde tú puedes verlo: en tu chat individual con el bot o, en un canal o chat grupal, en una respuesta marcada como Solo tú puedes ver este mensaje. El enlace vincula con la cuenta de quien lo abre a la persona para quien se generó, por lo que nunca aparece donde otros puedan verlo. Si Teams rechaza esa respuesta privada, el bot envía el enlace a tu chat privado con él y lo indica en la conversación. Teams solo lo permite cuando agregaste la aplicación para ti; de lo contrario, la tarjeta te pide que abras un chat privado con el bot y envíes /login allí. Un mensaje que hayas enviado en el canal sin tener la cuenta vinculada se procesa una vez que te conectes, siempre que lo hagas dentro de los 10 minutos. Cuando termines de conectarte en el navegador, el chat privado con el bot confirma con qué cuenta de Beeuni quedaste vinculado.

El enlace para iniciar sesión se puede usar una sola vez y vence después de 10 minutos. Una cuenta de Teams ya conectada a una cuenta de Beeuni no se puede conectar a otra: envía primero /logout. Si tu organización requiere autenticación en dos pasos, Beeuni te pide el segundo factor antes de conectarte, y el chat se ejecuta con el factor que usaste para conectarte. Si el enlace se generó sin ese factor, te pedirá que vuelvas a conectarte.

Cuando alguien sin acceso lo solicita, todos los propietarios y administradores de la cuenta reciben la solicitud en Beeuni. Quienes hayan vinculado Teams también la reciben en su chat privado con el bot, con un botón Revisar en Beeuni.

Respuestas privadas

En un canal o chat grupal, lo que el bot le dice a una persona solo es visible para esa persona y aparece marcado como Solo tú puedes ver este mensaje, igual que los mensajes efímeros de Slack:

• las respuestas a tus comandos;
• la tarjeta para conectar tu cuenta o solicitar acceso;
• el motivo por el que tu mensaje no se ejecutó: la política de incorporación o un agente que no puedes usar;
• en aprobación, la tarjeta Aprobar / Denegar del propietario y la decisión para quien hizo la solicitud.

La tarjeta En curso… que todos ven solo aparece cuando tu mensaje puede ejecutarse. Teams elimina las respuestas privadas al cabo de 24 horas. Si Teams rechaza una respuesta privada, el bot publica la tarjeta para toda la conversación. El enlace de inicio de sesión es la excepción: en ese caso, se envía a tu chat privado con el bot, nunca a la conversación.

Roles y permisos

Un chat no tiene credenciales propias de Beeuni, así que cada acción se realiza con la cuenta de Beeuni vinculada de quien la lleva a cabo y con el rol de proyecto de esa cuenta. Los propietarios y administradores de la cuenta cuentan como administradores del proyecto.

Una persona excluida de un agente no puede iniciar una sesión con él desde Teams, igual que en Beeuni.

Comandos

Escríbelos en un chat con el bot (en un canal, menciónalo primero con @):

En cualquier mensaje, ⋯ → Abrir en Beeuni abre la sesión a la que pertenece esa conversación. Cuando agregas la aplicación para ti, tu chat privado con el bot comienza con el mismo resumen que /home.

Modelos y claves

/models muestra todos los modelos que puedes ejecutar aquí, igual que el selector web: modelos de Beeuni y modelos disponibles mediante una clave de API de proveedor o una suscripción a ChatGPT. Cada uno indica cómo se paga. Si la lista es larga, aparece como un menú desplegable con búsqueda. Toca un modelo o escribe /model <id>; /model default vuelve al modelo predeterminado del proyecto.

Las claves disponibles dependen del chat:

• Un chat personal con el bot: tus propias claves y suscripción a ChatGPT, además de las claves compartidas con el proyecto. Sus sesiones son privadas para ti.
• Un chat grupal o canal: solo las claves compartidas con todo el proyecto. El chat es compartido y una clave personal permitiría que todos los participantes usaran la suscripción de una persona. En su lugar, elige ese modelo en un chat personal.

Un modelo que usa claves utiliza todas las claves que puedes usar para su proveedor y las alterna cuando se alcanzan los límites de uso. La elección se aplica al siguiente mensaje; el chat conserva su sesión. Para cambiar el modelo de una sesión en curso hace falta una cuenta vinculada y, con la política owner o approval, solo el propietario de la sesión puede cambiarlo. Un chat personal cuya sesión comenzó antes de que las sesiones se volvieran privadas sigue compartiendo esa sesión con el proyecto: /model lo indica y /new inicia una sesión privada. Consulta Claves de proveedor y acceso de miembros.

Mientras trabaja el agente

El agente responde en una sola tarjeta: primero muestra sus pasos mientras trabaja y luego la respuesta. Si la respuesta es larga, se corta al final de una línea, se indica que está truncada y se incluye un enlace a la sesión completa en Beeuni. Otro mensaje espera a que termine la ejecución actual y luego obtiene su propia tarjeta. Un paso silencioso no cierra una ejecución; solo lo hace cuando termina el entorno de ejecución.

Detener una ejecución

Mientras el agente trabaja, su tarjeta activa incluye un botón Detener. /stop hace lo mismo cuando la tarjeta ya no está a la vista. Cualquiera de las dos opciones detiene la ejecución en el entorno de ejecución, no solo en la tarjeta: una ejecución que se deja abierta absorbe el siguiente mensaje de la conversación en vez de responderlo.

Quien envió el mensaje que se está respondiendo puede detenerlo, al igual que cualquier persona aprobada en esa sesión, siempre que aún pueda usar el proyecto. Quien solo observa el canal no puede hacerlo, ni tampoco alguien aprobado en una sesión anterior del chat.

Archivos

El agente envía archivos con teams send --file. Las imágenes aparecen insertadas en los chats personales, grupales y de canal. Si una imagen supera el tamaño permitido, se muestra una tarjeta de consentimiento de OneDrive en un chat personal o se recurre a los archivos del equipo en un canal; un chat grupal no puede recibir transferencias de gran tamaño. Los demás archivos llegan como una tarjeta de consentimiento en un chat personal o como enlace de SharePoint cuando se comparten con un equipo. El agente puede descargar y usar los archivos entrantes y las imágenes pegadas, incluidas las imágenes insertadas en el cuerpo de un mensaje de canal.

• Una imagen pegada en un canal o chat grupal solo se descarga si el agente puede leer ese hilo o chat, según las reglas de Leer un canal. De lo contrario, teams download responde 403.
• La descarga se detiene al llegar a 50 MB y responde 413.
• teams history y teams thread muestran las imágenes insertadas de una publicación (images, cada una es una URL para teams download) y los nombres de los archivos compartidos desde SharePoint (files). El agente no puede descargar archivos de SharePoint.

Pega una captura de pantalla y pregunta sobre ella: el turno se ejecuta en un modelo capaz de leer imágenes, aunque el modelo propio de la conversación solo admita texto; la selección de modelo de la sesión no cambia. Si el modelo de la sesión ya no se puede ejecutar —por ejemplo, porque se revocó una clave o el chat no puede usar una suscripción a ChatGPT—, se sustituye para ese mensaje del mismo modo, en lugar de que falle.

Preguntas y formularios

El agente pregunta con controles, no con prosa. Una pregunta con hasta seis opciones muestra un botón por opción. Varias preguntas, una pregunta de selección múltiple o una lista más larga muestran un formulario con un campo para tu propia respuesta. Las fechas, horas, números y opciones de sí/no usan los campos correspondientes. Tu respuesta le llega al agente como tu próximo mensaje, etiquetada con la pregunta que responde. También puedes escribir una respuesta.

Aprobaciones

Cuando un agente necesita que una persona tome una decisión antes de continuar —un paso arriesgado, un cambio que quiere someter a aprobación—, crea un elemento para revisión. Si la sesión se inició desde esta conversación, la decisión llega aquí en forma de tarjeta: el título, un resumen, un nivel de riesgo y las opciones Approve, Request changes y Deny, además de un enlace a Beeuni.

La tarjeta incluye un campo de comentarios opcional. Lo que escribas se guarda con la decisión y se envía al agente junto con ella, así que «Request changes» no requiere otra ronda para preguntar qué quisiste decir. Es opcional por diseño: una simple aprobación no debería requerir que escribas nada.

Cualquiera en la conversación puede ver la tarjeta, pero para actuar se necesita una cuenta de Beeuni vinculada con acceso al proyecto.

Publicar por cuenta propia

Además de responder donde se le pidió, el agente puede publicar en cualquier chat o canal donde ya esté el bot para este proyecto: un resumen nocturno, una alerta, un traspaso. No puede acceder a una conversación a la que nunca se lo agregó.

Cuando no se inicia una sesión

Beeuni explica qué falla en vez de pedirte que vuelvas a intentarlo, porque la mayoría de los problemas al iniciar no se resuelven reintentando: una plantilla de sandbox que ya no existe, una cuenta sin vincular, un proyecto al que no puedes acceder o un espacio de trabajo sin créditos. En cada caso se indica cómo solucionarlo y el comando correspondiente.

Si se eliminó o cambió el nombre del agente asignado a la conversación, el error aparece como un selector: elige un agente disponible y vuelve a enviar tu mensaje. La lista solo muestra los agentes a los que tienes acceso.

Leer un canal

En un canal, el bot solo recibe los mensajes que lo mencionan, así que el agente no tiene en su sesión el debate sobre el que le preguntaron. Cuando necesita ese contexto, lee el hilo donde lo mencionaron o las publicaciones recientes del canal mediante el permiso ChannelMessage.Read.Group que solicita la aplicación al agregarla a un equipo. Si un equipo agregó la aplicación antes de que se solicitara ese permiso, debe actualizarla: consulta Actualizar la aplicación. En un chat personal, todos los mensajes ya llegan a la sesión, así que no hay mensajes anteriores que leer.

Todos los proyectos conectados al mismo inquilino de Microsoft 365 usan la misma aplicación, por lo que Beeuni limita cada lectura a las conversaciones propias del proyecto. En un canal, cada publicación nueva es una conversación independiente:

Si se rechaza una lectura, se responde a 403 con el motivo conversation_not_in_project y un mensaje que indica el canal o el hilo. Para leer en un inquilino con varios proyectos un canal del primer tipo, menciona al bot en él y selecciona este proyecto.

get_channel y list_channels responden sobre los canales estándar. Un canal privado o compartido solo aparece si el agente puede leerlo según las reglas anteriores. get_team, list_members, get_user y list_teams leen el directorio del inquilino y no tienen restricciones.

Límites

Los bots de Teams no pueden agregar reacciones a los mensajes ni buscar mensajes: esas funciones disponibles en Slack no tienen equivalente en Teams. El agente solo puede leer un canal de un equipo al que se haya agregado la aplicación y únicamente según las reglas de Leer un canal.