Configurar la integración de Slack

Esta guía te muestra cómo conectar Slack a un espacio de trabajo de Control Center, ya sea dejando que Control Center cree la app o construyéndola tú mismo.

Para un primer recorrido guiado, consulta Conecta Slack a tu espacio de trabajo.

Slack es el único proveedor de chat

El puente está escrito sin conocer al proveedor —una interfaz dirigida por descriptores sobre un adaptador por proveedor—, pero Slack es el único adaptador que existe. No hay ninguna implementación de Discord, Telegram, Teams o Matrix.

Requisitos previos

• El rol owner o admin en el espacio de trabajo de Control Center — conectar una app de chat es un cambio en los ajustes del espacio de trabajo
• Permiso para crear e instalar apps en el espacio de trabajo de Slack
• Nada accesible públicamente: la conexión es saliente (Socket Mode), así que el servidor no necesita puerto de entrada, túnel ni dominio

Tres formas de obtener la app

Ruta	Tú proporcionas	Control Center hace
Guiada	Un token de configuración de la app (xoxe-…)	Crea la app con los ámbitos, eventos, Socket Mode y comando slash correctos; te entrega los dos pasos para los que Slack no tiene API
Crear en Slack	Nada	Abre Slack con la misma configuración prerrellenada; eliges un espacio de trabajo y confirmas
A mano	Los tokens de la app terminada	Los verifica y conecta

La ruta guiada es la única que además deja la app gestionable desde Control Center, que es lo que habilita Personalizar el bot de chat. Una app creada con Crear en Slack se puede promover a gestionada más adelante pegando un token de configuración en el diálogo de conexión.

Deliberadamente no hay ningún botón de «instalar la app de Slack de Control Center». Instalar una app de Slack distribuida requiere un secreto de cliente compartido (Slack no tiene PKCE) y Socket Mode reparte los eventos de una app al azar entre sus conexiones, así que una app compartida entregaría los mensajes de tu espacio de trabajo a los servidores de otras personas. Por eso cada espacio de trabajo es dueño de su propia app, y estas tres rutas tratan de lo poco que eso te cuesta.

Opción A: deja que Control Center cree la app

1. Genera un par de tokens de configuración de la app en api.slack.com/apps y copia el token de refresco (xoxe-…)
2. En Control Center, ve a Ajustes → Espacio de trabajo → General y desplázate hasta la tarjeta Puentes de chat
3. En el bloque de Slack, haz clic en Crear la app por mí
4. Pega el token, ajusta el nombre de la app, el nombre del bot, las descripciones y el comando slash, y luego haz clic en Crear app
5. Sigue los dos pasos restantes que muestra el diálogo, cada uno como un enlace hacia Slack:
   • Basic Information → App-Level Tokens: genera un token con el ámbito connections:write (xapp-…)
   • Install App: instala en el espacio de trabajo y copia el Bot User OAuth Token (xoxb-…)
6. Haz clic en Pegar las credenciales y continúa con Conectar

El token de configuración rota en cada uso. Control Center guarda el valor rotado sobre la marcha, así que nunca tienes que pegarlo de nuevo.

Opción B: créala en Slack, prerrellenada

La misma app, sin token de configuración: Slack te entrega su propia pantalla de creación con todo el manifiesto ya rellenado.

1. En Control Center, ve a Ajustes → Espacio de trabajo → General y desplázate hasta la tarjeta Puentes de chat
2. En el bloque de Slack, haz clic en Crear la app por mí
3. Ajusta el nombre de la app, el nombre del bot, las descripciones y el comando slash: estos viajan con el enlace
4. Haz clic en Crear en Slack. Tu navegador abre la página de creación de apps de Slack con la configuración prerrellenada
5. Elige el espacio de trabajo de Slack y confirma. Los ámbitos, eventos, Socket Mode y el comando slash ya son correctos
6. De vuelta en Control Center, sigue los dos pasos restantes que muestra el diálogo:
   • Basic Information → App-Level Tokens: genera un token con el ámbito connections:write (xapp-…)
   • Install App: instala en el espacio de trabajo y copia el Bot User OAuth Token (xoxb-…)
7. Haz clic en Pegar las credenciales y continúa con Conectar

Slack no informa qué app creó, así que Control Center no llega a conocer el id de la app y los enlaces del paso 6 van a tu lista de apps en lugar de directamente a esa app. Personalizar el bot necesita un token de configuración.

Opción C: construye la app tú mismo

Crea una app en api.slack.com/apps y luego configúrala así.

Socket Mode: actívalo y deja vacía cada URL de solicitud. Slack rechaza un manifiesto que pida Socket Mode y entrega por webhook a la vez.

Ámbitos del token de bot (OAuth & Permissions):

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Suscripciones a eventos (eventos de bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels y message.groups son lo que hace que funcione una respuesta dentro de un hilo de Slack ya vinculado. Sin ellos, solo llega la primera mención.

Comando slash: /cc (cualquier nombre sirve: el puente usa el comando con el que se invocó por última vez).

App Home: activa la pestaña Messages y déjala escribible, para que los miembros puedan enviar mensajes directos al bot.

Tokens: genera un token a nivel de app con connections:write, luego instala la app y copia el token de OAuth del usuario bot.

Conectar

1. Ve a Ajustes → Espacio de trabajo → General y desplázate hasta la tarjeta Puentes de chat
2. En el bloque de Slack, haz clic en Conectar Slack
3. Rellena los campos:

Campo	Valor	Dónde vive en Slack
Bot user OAuth token	xoxb-…	OAuth & Permissions → Bot User OAuth Token
App-level token	xapp-…	Basic Information → App-Level Tokens (connections:write)
App configuration refresh token (opcional)	xoxe-…	El par de tokens de configuración de la app en api.slack.com/apps

El prefijo de cada valor se comprueba en ambos lados antes de enviar nada, así que un valor pegado en el campo equivocado se rechaza con la misma frase en ambos casos.

4. Haz clic en Conectar

Control Center verifica el token de bot con auth.test de Slack antes de guardar nada, así que un error tipográfico se te informa en lugar de convertirse en un socket que nunca funciona en silencio. El token a nivel de app solo se puede comprobar abriendo el socket, así que uno incorrecto aparece un momento después como un error de conexión en la misma fila.

Sin el token de configuración de la app opcional, la conexión funciona bien: simplemente no puedes editar el bot desde Control Center.

Qué hace la conexión

• Guarda las credenciales en el directorio propio del espacio de trabajo, junto a su base de datos, con lectura solo para el propietario. Nunca vuelven a viajar a un cliente
• Abre una conexión Socket Mode para este espacio de trabajo y empieza a recibir menciones, respuestas en hilos de Slack, mensajes directos y comandos slash
• Reactiva cada hilo de Slack que se había vinculado antes, así que una reconexión continúa las conversaciones existentes en lugar de dejarlas varadas
• No cuesta nada para los espacios de trabajo sin app de chat: ni socket, ni temporizadores, ni tráfico

Dónde viven los tokens y por qué no en el llavero

Las credenciales del bot son un archivo JSON plano por proveedor en <dataDir>/<workspaceId>/chat_credentials/, escrito de forma atómica y con lectura solo para el propietario. Eso es deliberado, no un descuido: eliminar un espacio de trabajo desvincula ese directorio, así que sus tokens se van con él, y workspace.export y los respaldos copian workspace.db —no el directorio—, de modo que un espacio de trabajo que entregas a otra persona nunca lleva dentro tokens de bot activos. El corolario es que restaurar un espacio de trabajo en otro lugar implica volver a conectar Slack allí.

El acceso al puente es por pertenencia al espacio de trabajo, nunca por posesión de un token. Una cuenta de Slack tiene que estar vinculada a un usuario de Control Center que sea miembro con un rol de escritura. Conectar, desconectar, la configuración guiada, el enlace de configuración y la personalización del bot están todos restringidos a administradores.

Verificar

La fila de Slack muestra una etiqueta de estado: En vivo, Conectando…, Error de conexión (con el propio error de Slack al lado) o No conectado. Para comprobarlo de extremo a extremo:

1. En Slack, invita al bot a un canal: /invite @your-bot-name
2. Menciónalo con una solicitud
3. Aparece una respuesta en el hilo de Slack y un espacio correspondiente aparece en Control Center

Cada miembro que quiera usar el puente vincula luego su propia cuenta; consulta Vincular tu cuenta de Slack.

Cómo se ve una respuesta en Slack

Por encima de las palabras transmitidas hay una tarjeta agrupada con una fila por paso. La preparación es una fila cuyo título pasa de Working on it… a Cloning … y a Starting the agent…. El razonamiento agrega una fila Thinking…; cuando ese paso termina, puede aparecer en ella un pensamiento breve. Cada herramienta es su propia fila (Read lib/main.dart). La respuesta llega como texto normal bajo la tarjeta. La tarjeta se vuelve completa cuando el turno termina y con error cuando la ejecución falló, se interrumpió o alcanzó su límite de turnos.

La tarjeta arranca en el momento en que el bot acepta la mención —Working on it…—, así que el hilo de Slack no queda en silencio mientras el espacio de trabajo todavía se está construyendo. Tu primera mención en un canal de Slack crea la conversación, que clona los repos en los que trabaja el agente, así que esa fila de preparación pasa a decir Cloning acme/widgets…, luego Setting up Reviewer…, luego Starting the agent… y luego una fila Thinking… en cuanto el agente realmente razona. En un repositorio grande esa primera preparación tarda un rato; la tarjeta es la forma de saber que está trabajando en lugar de ignorarte. Las menciones posteriores en el mismo hilo de Slack siguen abriendo con Working on it…, pero se saltan los pasos de clonación porque el espacio de trabajo ya está ahí.

El razonamiento en forma de muro de texto y la salida de herramientas nunca salen de Control Center: el pensamiento de la fila Thinking… es una línea corta, no una transcripción. View in Control Center en la tarjeta abre la conversación completa en la app de escritorio: el enlace va a tu propio servidor de Control Center, que le pasa el navegador a la app.

Si no pasa nada al hacer clic, el servidor que envió el mensaje no es accesible desde la máquina en la que hiciste clic (por ejemplo, un servidor solo de bucle local consultado desde un teléfono) o Control Center no se está ejecutando allí. Un servidor sin dirección accesible envía una tarjeta sin botón en lugar de una que no lleva a ninguna parte.

Rotar un token

Vuelve a pegar el valor nuevo en el diálogo de conexión y haz clic en Conectar. Conectar reemplaza la conexión que estuviera en marcha para este espacio de trabajo, así que el socket se vuelve a marcar con las credenciales nuevas.

Los dos tokens obligatorios deben estar presentes en cada conexión. El token de configuración de la app opcional conserva su valor guardado cuando dejas el campo vacío, así que rotar un token de bot nunca te cuesta la capacidad de editar la app.

Desconectar

Haz clic en Desconectar en la fila de Slack (solo administradores). El socket se cierra y las credenciales se olvidan.

Los vínculos de espacios y usuarios sobreviven a propósito: volver a conectar la misma app restaura cada hilo de Slack vinculado. Son filas con alcance de espacio de trabajo, así que eliminar el espacio de trabajo las borra de todos modos.

Solución de problemas

La fila dice «Error de conexión»

Lee el error que se muestra junto a la etiqueta. Una credencial rechazada (invalid_auth, not_authed, token_revoked, account_inactive) es terminal: el puente deja de reintentar y espera tokens nuevos, porque reintentar para siempre un token revocado solo te gana un límite de velocidad. Vuelve a pegar los tokens en el diálogo de conexión.

Un error missing_scope significa que la app está instalada con menos ámbitos de los que el puente necesita. Agrega el ámbito que falta, reinstala la app en Slack y luego vuelve a conectar.

Cualquier cosa transitoria (un socket caído, un hipo de Slack) se reconecta sola con retroceso exponencial acotado a 30 segundos, y la rotación rutinaria de sockets de Slack no aumenta ese retroceso.

El bot no responde a una mención

• ¿Está el bot en el canal? Slack solo entrega los mensajes de canal a las apps que son miembros. Ejecuta /invite @your-bot-name
• ¿Estás vinculado? Un miembro sin vincular recibe una respuesta en ese hilo de Slack que explica cómo vincularse. Consulta Vincular tu cuenta de Slack
• ¿Eres miembro del espacio de trabajo con un rol de escritura? A un viewer o guest se le dice que su rol es de solo lectura. El puente nunca inicia trabajo en nombre de alguien a quien no puede atribuir
• ¿Tiene agentes el espacio de trabajo? Sin agentes, el mensaje se guarda pero no hay nadie que lo responda

Responde en un canal pero ignora los mensajes simples

Es intencionado. Fuera de un mensaje directo, el puente solo actúa sobre un mensaje que menciona al bot, o sobre una respuesta dentro de un hilo de Slack que ya posee. Todo lo demás es la conversación de otras personas.

Las respuestas llegan como un solo mensaje grande en lugar de en streaming

La fila dice «El streaming en vivo está desactivado para esta app de Slack: las respuestas llegan en un solo mensaje». Las respuestas en streaming de Slack necesitan la función Agents & AI Apps en un plan de pago; cuando Slack la rechaza, el puente deja de pedirla durante toda la vida de esa conexión y publica respuestas completas en su lugar. No se pierde nada: la transcripción completa siempre está en Control Center.

El streaming también necesita un anclaje de hilo de Slack, así que una respuesta que no tiene un hilo de Slack donde crecer se publica completa. La tarjeta de tarea llega igual en ambos casos: en una respuesta completa viaja en el mismo mensaje, ya terminada.

La respuesta no tiene ninguna tarjeta encima

Las tarjetas de tarea de Slack forman parte de la misma superficie nueva Agents & AI Apps que el streaming, y Slack solo la rechaza en el momento de la llamada. Cuando lo hace, Control Center conserva la respuesta y descarta la tarjeta durante toda la vida de esa conexión: una respuesta sin línea de estado es mejor que una línea de estado sin respuesta.

«Control Center necesita un token de configuración de la app para editar el bot»

La fila Personalizar el bot está desactivada porque la conexión no tiene token de configuración de la app. Esto es lo esperable en una app creada a mano o mediante Crear en Slack, porque Slack nunca le dijo a Control Center qué app es. Genera un par de tokens en api.slack.com/apps y vuelve a conectar con el token de refresco completado.

Una respuesta larga se corta

Slack limita un solo mensaje a 40,000 caracteres, así que el puente trunca a 39,000 y añade un puntero a Control Center: una respuesta acortada es mejor que una que Slack rechaza de plano. El texto completo siempre está en la transcripción del espacio.

Guías relacionadas

• Vincular tu cuenta de Slack
• Personalizar el bot de chat
• Puente de chat

Conceptos relacionados

• Puentes de chat