Configurar la integración con 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 es ajeno al proveedor por construcción —una interfaz guiada por descriptores con 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 ningún puerto de entrada, túnel ni dominio

Tres formas de obtener la app

Ruta	Tú aportas	Control Center hace
Guiada	Un token de configuración de la app (xoxe-…)	Crea la app con los ámbitos, los eventos, Socket Mode y el 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 precargada; tú eliges un espacio de trabajo y confirmas
A mano	Los tokens de la app terminada	Los verifica y la conecta

Solo la ruta guiada deja además 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 ascender más tarde a gestionada pegando un token de configuración en el diálogo de conexión.

No hay a propósito ningún botón «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 sola app compartida entregaría los mensajes de tu espacio de trabajo a los servidores de otras personas. Por eso cada espacio de trabajo posee 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 haz clic en Crear app
5. Sigue los dos pasos restantes que muestra el diálogo, cada uno como un enlace a Slack:
   • Basic Information → App-Level Tokens: genera un token con el ámbito connections:write (xapp-…)
   • Install App: instálala en el espacio de trabajo y copia el Bot User OAuth Token (xoxb-…)
6. Haz clic en Pegar las credenciales y continúa con Connect

El token de configuración rota en cada uso. Control Center guarda el valor rotado sobre la marcha, así que nunca tendrás que volver a pegarlo.

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

La misma app, sin token de configuración: Slack te entrega su propia pantalla de creación con 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: 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 precargada
5. Elige el espacio de trabajo de Slack y confirma. Los ámbitos, los 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: instálala en el espacio de trabajo y copia el Bot User OAuth Token (xoxb-…)
7. Haz clic en Pegar las credenciales y continúa con Connect

Slack no informa de qué app ha creado, así que Control Center no llega a conocer el id de la app y los enlaces del paso 6 llevan 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 toda URL de solicitud. Slack rechaza un manifiesto que pida Socket Mode y entrega por webhook a la vez.

Bot token scopes (OAuth & Permissions):

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

Event subscriptions (eventos del bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels y message.groups son lo que hace funcionar una respuesta dentro de un hilo de Slack ya puenteado. 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 editable, para que los miembros puedan enviar mensajes directos al bot.

Tokens: genera un token de aplicación con connections:write, instala luego la app y copia el token 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
Token del bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Token de aplicación	xapp-…	Basic Information → App-Level Tokens (connections:write)
Token de configuración de la app (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 la casilla equivocada se rechaza con la misma frase en cualquiera de los dos casos.

4. Haz clic en Conectar

Control Center verifica el token del bot con auth.test de Slack antes de guardar nada, así que un error tipográfico se te comunica a ti en lugar de convertirse en un socket que nunca funciona en silencio. El token de aplicación solo se puede demostrar 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 sin problema: lo único que no podrás es 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, legibles solo por el propietario. Nunca vuelven 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
• Rearma cada hilo de Slack que estuviera puenteado antes, de modo que una reconexión continúa las conversaciones existentes en lugar de dejarlas abandonadas
• No cuesta nada a los espacios de trabajo que no tienen 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 restringido al propietario. 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 las copias de seguridad 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 sitio implica volver a conectar Slack allí.

El acceso al puente es la pertenencia al espacio de trabajo, nunca la 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 error propio de Slack al lado) o Sin conectar. Para comprobarlo de extremo a extremo:

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

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

Cómo se ve una respuesta en Slack

Por encima de las palabras transmitidas en streaming 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 luego a Starting the agent…. El razonamiento añade una fila Thinking…; cuando ese paso termina, puede aparecer en ella un pensamiento corto. Cada herramienta es su propia fila (Read lib/main.dart). La respuesta llega como texto normal bajo la tarjeta. La tarjeta pasa a completa cuando termina el turno, y a con error cuando la ejecución falló, se interrumpió o alcanzó su límite de turnos.

La tarjeta empieza 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 repositorios en los que trabaja el agente, así que esa fila de preparación pasa a leer Cloning acme/widgets…, luego Setting up Reviewer…, luego Starting the agent…, y luego una fila Thinking… en cuanto el agente razona de verdad. En un repositorio grande, esa primera preparación tarda un rato; la tarjeta es la forma de saber que está trabajando y no ignorándote. Las menciones posteriores en el mismo hilo de Slack siguen abriéndose con Working on it… y después se saltan los pasos de clonado, porque el espacio de trabajo ya está ahí.

El razonamiento en forma de muro de texto y la salida de las 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 aplicación de escritorio; el enlace va a tu propio servidor de Control Center, que entrega el navegador a la aplicación.

Si no ocurre nada al hacer clic, o bien el servidor que envió el mensaje no es accesible desde la máquina en la que hiciste clic (un servidor que solo escucha en loopback, pulsado desde un teléfono, por ejemplo), o bien 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 abrir con las nuevas credenciales.

Los dos tokens obligatorios tienen que estar presentes en cada conexión. El token de configuración de la app opcional conserva su valor guardado cuando dejas la casilla vacía, así que rotar un token de bot nunca te cuesta la posibilidad 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 puenteado. Son filas con alcance de espacio de trabajo, así que eliminar el espacio de trabajo las quita de todos modos.

Solución de problemas

La fila dice «Error de conexión»

Lee el error que aparece 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 acarrea 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 necesita el puente. Añade el ámbito que falta, reinstala la app en Slack y vuelve a conectar.

Todo lo transitorio (un socket caído, un hipo de Slack) se reconecta solo 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 un 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 el espacio de trabajo algún agente? Sin agentes, el mensaje se guarda, pero no hay nadie que lo responda

Responde en un canal pero ignora los mensajes normales

Es lo previsto. 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 controla. 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 el resto de la vida de esa conexión y publica las respuestas enteras. No se pierde nada: la transcripción completa está siempre 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 en el que crecer se publica entera. La tarjeta de tarea llega de todos modos: en una respuesta entera viaja en el mismo mensaje, ya completa.

La respuesta no tiene 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 el resto de 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: 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 rellenado.

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 está siempre 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