Configurar a integração com o Slack

Este guia mostra como conectar o Slack a um espaço de trabalho do Control Center, seja deixando o Control Center criar o app, seja criando-o você mesmo.

Para uma primeira execução guiada, consulte Conecte o Slack ao seu espaço de trabalho.

O Slack é o único provedor de chat

A ponte é agnóstica de provedor por construção — uma interface guiada por descritor sobre um adaptador por provedor —, mas o Slack é o único adaptador que existe. Não há implementação de Discord, Telegram, Teams ou Matrix.

Pré-requisitos

• A função owner ou admin no espaço de trabalho do Control Center — conectar um app de chat é uma alteração nas configurações do espaço de trabalho
• Permissão para criar e instalar apps no espaço de trabalho do Slack
• Nada acessível publicamente: a conexão é de saída (Socket Mode), então o servidor não precisa de porta de entrada, túnel nem domínio

Três maneiras de obter o app

Caminho	Você fornece	O Control Center faz
Guiado	Um token de configuração do app (xoxe-…)	Cria o app com os escopos, eventos, Socket Mode e comando slash corretos; entrega a você as duas etapas para as quais o Slack não tem API
Criar no Slack	Nada	Abre o Slack com a mesma configuração pré-preenchida; você escolhe um espaço de trabalho e confirma
Manual	Os tokens do app já pronto	Verifica-os e conecta

O caminho guiado é o único que também deixa o app gerenciável a partir do Control Center, que é o que viabiliza Personalizar o bot de chat. Um app Criar no Slack pode ser promovido a gerenciado depois, colando um token de configuração no diálogo de conexão.

Não existe, de propósito, um botão “instalar o app do Slack do Control Center”. Instalar um app do Slack distribuído exige um client secret compartilhado (o Slack não tem PKCE) e o Socket Mode distribui os eventos de um app aleatoriamente entre suas conexões — então um app compartilhado entregaria as mensagens do seu espaço de trabalho aos servidores de outras pessoas. Por isso cada espaço de trabalho tem seu próprio app, e esses três caminhos tratam de quão pouco trabalho isso custa a você.

Opção A: deixe o Control Center criar o app

1. Gere um par de tokens de configuração do app em api.slack.com/apps e copie o token de atualização (xoxe-…)
2. No Control Center, vá em Configurações → Espaço de trabalho → Geral e role até o cartão Pontes de chat
3. No bloco do Slack, clique em Criar o app para mim
4. Cole o token, ajuste o nome do app, o nome do bot, as descrições e o comando slash e clique em Criar app
5. Siga as duas etapas restantes que o diálogo mostra, cada uma como um link para o Slack:
   • Basic Information → App-Level Tokens: gere um token com o escopo connections:write (xapp-…)
   • Install App: instale no espaço de trabalho e copie o Bot User OAuth Token (xoxb-…)
6. Clique em Colar as credenciais e continue em Conectar

O token de configuração é rotacionado a cada uso. O Control Center armazena o valor rotacionado à medida que avança, então você nunca precisa colá-lo de novo.

Opção B: crie-o no Slack, pré-preenchido

O mesmo app, sem token de configuração — o Slack entrega a você sua própria tela de criação com todo o manifesto já preenchido.

1. No Control Center, vá em Configurações → Espaço de trabalho → Geral e role até o cartão Pontes de chat
2. No bloco do Slack, clique em Criar o app para mim
3. Ajuste o nome do app, o nome do bot, as descrições e o comando slash — tudo isso viaja com o link
4. Clique em Criar no Slack. Seu navegador abre a página de criação de app do Slack com a configuração pré-preenchida
5. Escolha o espaço de trabalho do Slack e confirme. Os escopos, os eventos, o Socket Mode e o comando slash já estão corretos
6. De volta ao Control Center, siga as duas etapas restantes que o diálogo mostra:
   • Basic Information → App-Level Tokens: gere um token com o escopo connections:write (xapp-…)
   • Install App: instale no espaço de trabalho e copie o Bot User OAuth Token (xoxb-…)
7. Clique em Colar as credenciais e continue em Conectar

O Slack não informa qual app criou, então o Control Center não descobre o id do app e os links da etapa 6 vão para a sua lista de apps em vez de irem direto para esse app. Personalizar o bot precisa de um token de configuração.

Opção C: crie o app você mesmo

Crie um app em api.slack.com/apps e configure-o assim.

Socket Mode: ative-o e deixe toda URL de requisição vazia. O Slack recusa um manifesto que pede Socket Mode e entrega por webhook ao mesmo tempo.

Escopos do token de bot (OAuth & Permissions):

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

Assinaturas de eventos (eventos de bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels e message.groups são o que faz uma resposta dentro de um thread do Slack já vinculado funcionar. Sem eles, só a primeira menção chega.

Comando slash: /cc (qualquer nome serve — a ponte usa o comando com que foi invocada por último).

App Home: ative a aba Messages e deixe-a gravável, para que os membros possam enviar mensagens diretas ao bot.

Tokens: gere um token de aplicação com connections:write, depois instale o app e copie o token OAuth do usuário bot.

Conectar

1. Vá em Configurações → Espaço de trabalho → Geral e role até o cartão Pontes de chat
2. No bloco do Slack, clique em Conectar Slack
3. Preencha os campos:

Campo	Valor	Onde fica no Slack
Token OAuth do usuário bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Token de aplicação	xapp-…	Basic Information → App-Level Tokens (connections:write)
Token de atualização da configuração do app (opcional)	xoxe-…	O par de tokens de configuração do app em api.slack.com/apps

O prefixo de cada valor é verificado nos dois lados antes que qualquer coisa seja enviada, então um valor colado na caixa errada é recusado com a mesma frase dos dois jeitos.

4. Clique em Conectar

O Control Center verifica o token de bot com o auth.test do Slack antes de armazenar qualquer coisa, então um erro de digitação é relatado a você em vez de virar um socket que nunca funciona silenciosamente. O token de aplicação só pode ser comprovado abrindo o socket, então um token ruim aparece um instante depois como um erro de conexão na mesma linha.

Sem o token de configuração do app opcional, a conexão funciona normalmente — você só não consegue editar o bot a partir do Control Center.

O que a conexão faz

• Armazena as credenciais no diretório do próprio espaço de trabalho, ao lado do banco de dados, legíveis apenas pelo proprietário. Elas nunca voltam para um cliente
• Abre uma conexão Socket Mode para este espaço de trabalho e começa a receber menções, respostas em threads do Slack, mensagens diretas e comandos slash
• Rearma todos os threads do Slack que já haviam sido vinculados, de modo que uma reconexão continua conversas existentes em vez de abandoná-las
• Não custa nada para espaços de trabalho sem app de chat: nenhum socket, nenhum timer, nenhum tráfego

Onde ficam os tokens e por que não no chaveiro

As credenciais do bot ficam em um único arquivo JSON simples por provedor em <dataDir>/<workspaceId>/chat_credentials/, gravado atomicamente e restrito ao proprietário. Isso é de propósito, não um descuido: excluir um espaço de trabalho desvincula esse diretório, então seus tokens vão junto, e workspace.export e os backups copiam o workspace.db — não o diretório —, de modo que um espaço de trabalho entregue a outra pessoa nunca carrega tokens de bot ativos dentro de si. O corolário é que restaurar um espaço de trabalho em outro lugar significa reconectar o Slack lá.

O acesso à ponte é a associação ao espaço de trabalho, nunca a posse de um token. Uma conta do Slack precisa estar vinculada a um usuário do Control Center que seja membro com uma função de escrita. Conectar, desconectar, a configuração guiada, o link de configuração e a personalização do bot são todos restritos a admins.

Verificar

A linha do Slack mostra uma etiqueta de status: Ativo, Conectando…, Erro de conexão (com o próprio erro do Slack ao lado) ou Não conectado. Para verificar de ponta a ponta:

1. No Slack, convide o bot para um canal: /invite @your-bot-name
2. Mencione-o com um pedido
3. Uma resposta em thread do Slack aparece e um espaço correspondente aparece no Control Center

Cada membro que quiser usar a ponte vincula então a própria conta — consulte Vincular sua conta do Slack.

Como uma resposta aparece no Slack

Acima das palavras transmitidas em stream fica um cartão agrupado, com uma linha por etapa. A preparação é uma linha cujo título passa de Working on it… para Cloning … e então Starting the agent…. O raciocínio acrescenta uma linha Thinking…; quando essa etapa termina, um pensamento curto pode aparecer nela. Cada ferramenta é sua própria linha (Read lib/main.dart). A resposta chega como texto comum abaixo do cartão. O cartão fica completo quando o turno termina e com erro quando a execução falhou, foi interrompida ou atingiu seu limite de turnos.

O cartão começa no momento em que o bot aceita a menção — Working on it… —, então o thread do Slack não fica em silêncio enquanto o espaço de trabalho ainda está sendo criado. Sua primeira menção em um canal do Slack cria a conversa, o que clona os repositórios em que o agente trabalha, então essa linha de preparação depois exibe Cloning acme/widgets…, depois Setting up Reviewer…, depois Starting the agent… e, em seguida, uma linha Thinking… assim que o agente está de fato raciocinando. Em um repositório grande, essa primeira preparação leva um tempo; o cartão é como você percebe que ele está trabalhando, e não ignorando você. Menções posteriores no mesmo thread do Slack ainda abrem com Working on it… e depois pulam as etapas de clonagem, porque o espaço de trabalho já existe.

Raciocínio como uma parede de texto e a saída de ferramentas nunca saem do Control Center — o pensamento na linha Thinking… é uma linha curta, não uma transcrição. View in Control Center no cartão abre a conversa completa no app de desktop — o link aponta para o seu próprio servidor do Control Center, que entrega o navegador ao app.

Se nada acontecer quando você clicar nele, o servidor que enviou a mensagem não está acessível a partir da máquina em que você clicou (um servidor apenas em loopback clicado de um celular, por exemplo), ou o Control Center não está em execução nela. Um servidor sem endereço alcançável envia um cartão sem botão, em vez de um que não leva a lugar nenhum.

Rotacionar um token

Cole novamente o novo valor no diálogo de conexão e clique em Conectar. Conectar substitui qualquer conexão que estivesse em execução para este espaço de trabalho, então o socket é discado de novo com as novas credenciais.

Os dois tokens obrigatórios precisam estar presentes em toda conexão. O token de configuração do app opcional mantém o valor armazenado quando você deixa a caixa vazia, então rotacionar um token de bot nunca custa a você a capacidade de editar o app.

Desconectar

Clique em Desconectar na linha do Slack (somente admins). O socket é fechado e as credenciais são esquecidas.

Os vínculos de espaço e de usuário sobrevivem de propósito: reconectar o mesmo app restaura todos os threads do Slack vinculados. Eles são linhas com escopo de espaço de trabalho, então excluir o espaço de trabalho os remove de qualquer forma.

Solução de problemas

A linha diz “Erro de conexão”

Leia o erro mostrado ao lado da etiqueta. Uma credencial rejeitada (invalid_auth, not_authed, token_revoked, account_inactive) é terminal — a ponte para de tentar de novo e espera novos tokens, porque tentar para sempre um token revogado só renderia um limite de taxa. Cole os tokens novamente no diálogo de conexão.

Um erro missing_scope significa que o app está instalado com menos escopos do que a ponte precisa. Adicione o escopo que falta, reinstale o app no Slack e reconecte.

Qualquer coisa transitória (um socket derrubado, uma instabilidade do Slack) reconecta sozinha com backoff exponencial limitado a 30 segundos, e a rotação rotineira de socket do Slack não escala esse backoff.

O bot não responde a uma menção

• O bot está no canal? O Slack só entrega mensagens de canal a apps que são membros. Execute /invite @your-bot-name
• Você está vinculado? Um membro não vinculado recebe uma resposta naquele thread do Slack explicando como vincular. Consulte Vincular sua conta do Slack
• Você é membro do espaço de trabalho com uma função de escrita? Um viewer ou guest é informado de que sua função é somente leitura. A ponte nunca inicia trabalho em nome de alguém a quem não consegue atribuir
• O espaço de trabalho tem algum agente? Sem agentes, a mensagem é armazenada, mas não há ninguém para respondê-la

Ele responde em um canal, mas ignora mensagens comuns

Isso é intencional. Fora de uma mensagem direta, a ponte só age sobre uma mensagem que menciona o bot ou uma resposta dentro de um thread do Slack que ela já possui. Todo o resto é conversa de outras pessoas.

As respostas chegam como uma mensagem grande em vez de streaming

A linha diz “O streaming ao vivo está desligado para este app do Slack — as respostas chegam numa única mensagem.” As respostas em streaming do Slack exigem o recurso Agents & AI Apps em um plano pago; quando o Slack o recusa, a ponte para de pedir pelo resto da vida daquela conexão e passa a publicar respostas inteiras. Nada se perde — a transcrição completa está sempre no Control Center.

O streaming também precisa de uma âncora de thread do Slack, então uma resposta que não tem um thread do Slack onde crescer é publicada inteira. O cartão de tarefa ainda chega de qualquer jeito: em uma resposta inteira, ele viaja na mesma mensagem, já completo.

A resposta não tem cartão acima dela

Os cartões de tarefa do Slack fazem parte da mesma superfície nova Agents & AI Apps que o streaming, e o Slack só recusa na hora da chamada. Quando isso acontece, o Control Center mantém a resposta e descarta o cartão pelo resto da vida daquela conexão — uma resposta sem uma linha de status é melhor que uma linha de status sem resposta.

“O Control Center precisa de um token de configuração do app para editar o bot”

A linha Personalizar o bot fica desativada porque a conexão não tem um token de configuração do app. Isso é esperado para um app criado manualmente ou por meio de Criar no Slack — o Slack nunca disse ao Control Center qual app é. Gere um par de tokens em api.slack.com/apps e reconecte com o token de atualização preenchido.

Uma resposta longa é cortada

O Slack limita uma única mensagem a 40.000 caracteres, então a ponte trunca em 39.000 e acrescenta um aviso apontando para o Control Center — uma resposta encurtada é melhor que uma que o Slack rejeita por completo. O texto completo está sempre na transcrição do espaço.

Guias relacionados

• Vincular sua conta do Slack
• Personalizar o bot de chat
• Ponte de chat

Conceitos relacionados

• Pontes de chat