Configura l'integrazione Slack

Questa guida mostra come collegare Slack a uno spazio di lavoro di Control Center, lasciando che sia Control Center a creare l’app oppure costruendola tu stesso.

Per una prima esecuzione guidata, vedi Collega Slack al tuo spazio di lavoro.

Slack è l’unico provider di chat

Il ponte è senza conoscenza del provider per costruzione — un’interfaccia guidata da un descrittore, con un adapter per provider — ma Slack è l’unico adapter che esiste. Non esiste alcuna implementazione per Discord, Telegram, Teams o Matrix.

Prerequisiti

• Il ruolo owner o admin nello spazio di lavoro di Control Center — connettere un’app di chat è una modifica alle impostazioni dello spazio di lavoro
• Il permesso di creare e installare app nello spazio di lavoro Slack
• Nulla di pubblicamente raggiungibile: la connessione è in uscita (Socket Mode), quindi il server non ha bisogno di porte in entrata, tunnel o dominio

Tre modi per ottenere l’app

Percorso	Cosa fornisci tu	Cosa fa Control Center
Guidata	Un token di configurazione dell’app (xoxe-…)	Crea l’app con gli scope, gli eventi, Socket Mode e il comando slash corretti; ti consegna i due passaggi per cui Slack non ha un’API
Crea in Slack	Nulla	Apre Slack con la stessa configurazione precompilata; scegli uno spazio di lavoro e confermi
A mano	I token dell’app finita	Li verifica e si connette

Il percorso guidato è l’unico che lascia l’app anche gestibile da Control Center, ed è ciò che abilita Personalizza il bot di chat. Un’app creata con Crea in Slack può essere promossa in seguito ad app gestita incollando un token di configurazione nella finestra di connessione.

Non esiste di proposito alcun pulsante «installa l’app Slack di Control Center». Installare un’app Slack distribuita richiede un client secret condiviso (Slack non ha PKCE) e Socket Mode distribuisce gli eventi di un’app in modo casuale tra le sue connessioni: una sola app condivisa consegnerebbe quindi i messaggi del tuo spazio di lavoro ai server di altre persone. Ogni spazio di lavoro possiede perciò la propria app, e questi tre percorsi servono a mostrare quanto poco lavoro ti costa.

Opzione A: lascia che Control Center crei l’app

1. Genera una coppia di token di configurazione dell’app su api.slack.com/apps e copia il token di aggiornamento (xoxe-…)
2. In Control Center, vai in Impostazioni → Spazio di lavoro → Generale e scorri fino alla scheda Ponti di chat
3. Nel blocco di Slack, fai clic su Crea l’app per me
4. Incolla il token, regola il nome dell’app, il nome del bot, le descrizioni e il comando slash, poi fai clic su Crea l’app
5. Segui i due passaggi rimanenti che la finestra mostra, ciascuno come link verso Slack:
   • Basic Information → App-Level Tokens: genera un token con lo scope connections:write (xapp-…)
   • Install App: installa nello spazio di lavoro e copia il Bot User OAuth Token (xoxb-…)
6. Fai clic su Incolla le credenziali e prosegui con Connetti

Il token di configurazione ruota a ogni utilizzo. Control Center memorizza il valore ruotato man mano, quindi non dovrai più incollarlo.

Opzione B: creala in Slack, precompilata

Stessa app, nessun token di configurazione: Slack ti presenta la propria schermata di creazione con l’intero manifest già compilato.

1. In Control Center, vai in Impostazioni → Spazio di lavoro → Generale e scorri fino alla scheda Ponti di chat
2. Nel blocco di Slack, fai clic su Crea l’app per me
3. Regola il nome dell’app, il nome del bot, le descrizioni e il comando slash: questi valori viaggiano con il link
4. Fai clic su Crea in Slack. Il browser apre la pagina di creazione dell’app di Slack con la configurazione precompilata
5. Scegli lo spazio di lavoro Slack e conferma. Gli scope, gli eventi, Socket Mode e il comando slash sono già corretti
6. Di nuovo in Control Center, segui i due passaggi rimanenti che la finestra mostra:
   • Basic Information → App-Level Tokens: genera un token con lo scope connections:write (xapp-…)
   • Install App: installa nello spazio di lavoro e copia il Bot User OAuth Token (xoxb-…)
7. Fai clic su Incolla le credenziali e prosegui con Connetti

Slack non comunica quale app ha creato, quindi Control Center non ne apprende l’id e i link del passaggio 6 portano all’elenco delle tue app anziché direttamente a quell’app. Personalizza il bot richiede un token di configurazione.

Opzione C: costruisci l’app da te

Crea un’app su api.slack.com/apps, poi configurala come segue.

Socket Mode: abilitalo e lascia vuoto ogni request URL. Slack rifiuta un manifest che richiede sia Socket Mode sia la consegna tramite webhook.

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 (eventi del bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels e message.groups sono ciò che fa funzionare una risposta dentro un thread di Slack già collegato al ponte. Senza di essi arriva soltanto la prima menzione.

Slash command: /cc (qualsiasi nome va bene: il ponte usa il comando con cui è stato invocato l’ultima volta).

App Home: abilita la scheda Messages e lasciala scrivibile, così i membri possono inviare messaggi diretti al bot.

Tokens: genera un token a livello di app con connections:write, poi installa l’app e copia il token OAuth dell’utente bot.

Connetti

1. Vai in Impostazioni → Spazio di lavoro → Generale e scorri fino alla scheda Ponti di chat
2. Nel blocco di Slack, fai clic su Connetti Slack
3. Compila i campi:

Campo	Valore	Dove si trova in Slack
Token OAuth dell’utente bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Token a livello di app	xapp-…	Basic Information → App-Level Tokens (connections:write)
Token di aggiornamento della configurazione dell’app (facoltativo)	xoxe-…	La coppia di token di configurazione dell’app su api.slack.com/apps

Il prefisso di ogni valore viene controllato su entrambi i lati prima che qualsiasi cosa venga inviata, quindi un valore incollato nel campo sbagliato viene rifiutato con la stessa frase in entrambi i casi.

4. Fai clic su Connetti

Control Center verifica il token del bot con auth.test di Slack prima di memorizzare qualsiasi cosa, quindi un refuso ti viene segnalato invece di diventare un socket che non funziona mai in silenzio. Il token a livello di app può essere dimostrato solo aprendo il socket, quindi uno errato compare un attimo dopo come errore di connessione sulla stessa riga.

Senza il token di configurazione dell’app facoltativo la connessione funziona bene: semplicemente non puoi modificare il bot da Control Center.

Cosa fa la connessione

• Memorizza le credenziali nella directory propria dello spazio di lavoro, accanto al suo database, leggibili solo dal proprietario. Non tornano mai indietro verso un client
• Apre una connessione Socket Mode per questo spazio di lavoro e inizia a ricevere menzioni, risposte nei thread di Slack, messaggi diretti e comandi slash
• Riattiva ogni thread di Slack già collegato in precedenza, così una riconnessione prosegue le conversazioni esistenti invece di abbandonarle
• Non costa nulla per gli spazi di lavoro che non hanno un’app di chat: nessun socket, nessun timer, nessun traffico

Dove vivono i token e perché non nel portachiavi

Le credenziali del bot sono un semplice file JSON per provider in <dataDir>/<workspaceId>/chat_credentials/, scritto in modo atomico e reso accessibile solo al proprietario. È una scelta deliberata, non una svista: eliminare uno spazio di lavoro scollega quella directory, così i suoi token se ne vanno con essa, e workspace.export e i backup copiano workspace.db — non la directory — quindi uno spazio di lavoro che passi a qualcun altro non contiene mai al suo interno token del bot attivi. Il corollario è che ripristinare uno spazio di lavoro altrove significa riconnettere Slack lì.

L’accesso al ponte è l’appartenenza allo spazio di lavoro, mai il possesso di un token. Un account Slack deve essere collegato a un utente di Control Center che sia membro con un ruolo di scrittura. Connessione, disconnessione, configurazione guidata, link di configurazione e personalizzazione del bot richiedono tutti i privilegi di amministratore.

Verifica

La riga di Slack mostra un’etichetta di stato: In linea, Connessione…, Errore di connessione (con l’errore di Slack accanto) o Non connesso. Per verificare dall’inizio alla fine:

1. In Slack, invita il bot in un canale: /invite @your-bot-name
2. Menzionalo con una richiesta
3. Compare una risposta nel thread di Slack e uno spazio corrispondente in Control Center

Ogni membro che vuole usare il ponte collega poi il proprio account: vedi Collega il tuo account Slack.

Come appare una risposta in Slack

Sopra le parole trasmesse in streaming si trova un’unica scheda raggruppata, con una riga per ogni passaggio. La preparazione è un’unica riga il cui titolo passa da Working on it… a Cloning … a Starting the agent…. Il ragionamento aggiunge una riga Thinking…; quando quel passaggio termina, su di essa può comparire un breve pensiero. Ogni strumento ha la propria riga (Read lib/main.dart). La risposta arriva come testo normale sotto la scheda. La scheda diventa completa quando il turno finisce, e in errore quando l’esecuzione è fallita, è stata interrotta o ha raggiunto il suo limite di turni.

La scheda inizia nel momento in cui il bot accetta la menzione — Working on it… — così il thread di Slack non resta in silenzio mentre lo spazio di lavoro è ancora in costruzione. La tua prima menzione in un canale Slack crea la conversazione, che clona i repo in cui lavora l’agente, quindi quella riga di preparazione legge poi Cloning acme/widgets…, poi Setting up Reviewer…, poi Starting the agent…, infine una riga Thinking… quando l’agente ragiona davvero. Su un repository grande quella prima preparazione richiede un po’ di tempo; la scheda è il modo in cui capisci che sta lavorando invece di ignorarti. Le menzioni successive nello stesso thread di Slack si aprono comunque con Working on it…, poi saltano i passaggi di clonazione perché lo spazio di lavoro è già lì.

Il ragionamento come muro di testo e l’output degli strumenti non lasciano mai Control Center: il pensiero sulla riga Thinking… è una riga breve, non una trascrizione. View in Control Center sulla scheda apre la conversazione completa nell’app desktop: il link punta al tuo server di Control Center, che passa il browser all’app.

Se non succede nulla quando ci fai clic, il server che ha inviato il messaggio non è raggiungibile dalla macchina da cui hai fatto clic (per esempio un server solo loopback aperto da un telefono), oppure Control Center non è in esecuzione lì. Un server senza un indirizzo raggiungibile invia una scheda senza pulsante, anziché una che non porta da nessuna parte.

Ruota un token

Incolla di nuovo il nuovo valore nella finestra di connessione e fai clic su Connetti. La connessione sostituisce quella che era in esecuzione per questo spazio di lavoro, quindi il socket viene ricomposto con le nuove credenziali.

I due token obbligatori devono essere presenti a ogni connessione. Il token di configurazione dell’app facoltativo conserva il valore memorizzato quando lasci il campo vuoto, quindi ruotare un token del bot non ti costa mai la possibilità di modificare l’app.

Disconnetti

Fai clic su Disconnetti sulla riga di Slack (solo amministratori). Il socket si chiude e le credenziali vengono dimenticate.

I collegamenti di spazi e utenti sopravvivono di proposito: riconnettere la stessa app ripristina ogni thread di Slack collegato al ponte. Sono righe con ambito di spazio di lavoro, quindi eliminare lo spazio di lavoro le rimuove comunque.

Risoluzione dei problemi

La riga dice «Errore di connessione»

Leggi l’errore mostrato accanto all’etichetta. Una credenziale rifiutata (invalid_auth, not_authed, token_revoked, account_inactive) è definitiva: il ponte smette di riprovare e aspetta nuovi token, perché riprovare all’infinito un token revocato non fa che guadagnarti un limite di frequenza. Incolla di nuovo i token nella finestra di connessione.

Un errore missing_scope significa che l’app è installata con meno scope di quanti ne serva al ponte. Aggiungi lo scope mancante, reinstalla l’app in Slack, poi riconnettiti.

Qualsiasi cosa transitoria (un socket caduto, un intoppo di Slack) si riconnette da sola con un backoff esponenziale limitato a 30 secondi, e la rotazione di routine del socket da parte di Slack non aumenta quel backoff.

Il bot non risponde a una menzione

• Il bot è nel canale? Slack consegna i messaggi di canale solo alle app che ne sono membri. Esegui /invite @your-bot-name
• Sei collegato? Un membro non collegato riceve una risposta in quel thread di Slack che spiega come collegarsi. Vedi Collega il tuo account Slack
• Sei un membro dello spazio di lavoro con un ruolo di scrittura? A un viewer o guest viene detto che il suo ruolo è di sola lettura. Il ponte non avvia mai lavoro per conto di qualcuno che non riesce ad attribuire
• Lo spazio di lavoro ha degli agenti? Senza agenti, il messaggio viene memorizzato ma non ha nessuno che risponda

Risponde in un canale ma ignora i messaggi semplici

È voluto. Al di fuori di un messaggio diretto, il ponte agisce solo su un messaggio che menziona il bot, oppure su una risposta dentro un thread di Slack che lui già possiede. Tutto il resto è la conversazione di altre persone.

Le risposte arrivano come un unico grande messaggio anziché in streaming

La riga dice «Lo streaming in tempo reale è disattivato per questa app Slack: le risposte arrivano in un unico messaggio.» Le risposte in streaming di Slack richiedono la funzione Agents & AI Apps su un piano a pagamento; quando Slack la rifiuta, il ponte smette di chiederla per tutta la vita di quella connessione e pubblica invece risposte intere. Non si perde nulla: la trascrizione completa è sempre in Control Center.

Lo streaming richiede anche un’ancora di thread di Slack, quindi una risposta che non ha un thread di Slack in cui crescere viene pubblicata intera. La scheda delle attività arriva comunque in entrambi i casi: su una risposta intera viaggia nello stesso messaggio, già completa.

La risposta non ha una scheda sopra

Le schede delle attività di Slack fanno parte della stessa nuova superficie Agents & AI Apps dello streaming, e Slack rifiuta solo al momento della chiamata. Quando lo fa, Control Center conserva la risposta e abbandona la scheda per tutta la vita di quella connessione: una risposta senza riga di stato batte una riga di stato senza risposta.

«Control Center ha bisogno di un token di configurazione dell’app per modificare il bot»

La riga Personalizza il bot è disattivata perché la connessione non ha alcun token di configurazione dell’app. È previsto per un’app creata a mano o tramite Crea in Slack: Slack non ha mai detto a Control Center di quale app si tratta. Genera una coppia di token su api.slack.com/apps e riconnettiti con il token di aggiornamento compilato.

Una risposta lunga viene troncata

Slack limita un singolo messaggio a 40.000 caratteri, quindi il ponte tronca a 39.000 e aggiunge un rimando a Control Center: una risposta accorciata batte una che Slack rifiuta del tutto. Il testo completo è sempre nella trascrizione dello spazio.

Guide correlate

• Collega il tuo account Slack
• Personalizza il bot di chat
• Ponte di chat

Concetti correlati

• Ponti di chat