Configurar a integração com o Slack

Este guia mostra-lhe como ligar o Slack a um espaço de trabalho do Control Center, quer deixando o Control Center criar a aplicação, quer construindo-a por si mesmo.

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

O Slack é o único fornecedor de chat

A ponte é escrita sem conhecer o fornecedor, por construção — uma interface orientada por descritores, com um adaptador por fornecedor —, mas o Slack é o único adaptador que existe. Não existe nenhuma implementação de Discord, Telegram, Teams ou Matrix.

Pré-requisitos

• O papel owner ou admin no espaço de trabalho do Control Center — ligar uma aplicação de chat é uma alteração das definições do espaço de trabalho
• Autorização para criar e instalar aplicações no espaço de trabalho do Slack
• Nada acessível publicamente: a ligação é de saída (Socket Mode), pelo que o servidor não precisa de porta de entrada, túnel nem domínio

Três formas de obter a aplicação

Caminho	O que fornece	O que o Control Center faz
Guiado	Um token de configuração da aplicação (xoxe-…)	Cria a aplicação com os âmbitos, os eventos, o Socket Mode e o comando slash corretos; entrega-lhe os dois passos para os quais o Slack não tem API
Criar no Slack	Nada	Abre o Slack com a mesma configuração pré-preenchida; escolhe um espaço de trabalho e confirma
À mão	Os tokens da aplicação final	Verifica-os e liga

O caminho guiado é o único que também deixa a aplicação gerível a partir do Control Center, e é isso que permite Personalizar o bot de chat. Uma aplicação criada com Criar no Slack pode ser promovida mais tarde a aplicação gerida, colando um token de configuração na caixa de diálogo de ligação.

Não existe deliberadamente nenhum botão «instalar a aplicação Slack do Control Center». Instalar uma aplicação Slack distribuída exige um segredo de cliente partilhado (o Slack não tem PKCE) e o Socket Mode distribui os eventos de uma aplicação aleatoriamente pelas suas ligações — pelo que uma aplicação partilhada entregaria as mensagens do seu espaço de trabalho aos servidores de outras pessoas. Cada espaço de trabalho tem, por isso, a sua própria aplicação, e estes três caminhos existem para lhe mostrar quão pouco trabalho isso lhe custa.

Opção A: deixar o Control Center criar a aplicação

1. Gere um par de tokens de configuração da aplicação em api.slack.com/apps e copie o token de renovação (xoxe-…)
2. No Control Center, vá a Definições → Espaço de trabalho → Geral e desloque-se até ao cartão Pontes de chat
3. No bloco do Slack, clique em Criar a aplicação para mim
4. Cole o token, ajuste o nome da aplicação, o nome do bot, as descrições e o comando slash, e clique em Criar aplicação
5. Siga os dois passos restantes que a caixa de diálogo mostra, cada um como uma ligação para o Slack:
   • Basic Information → App-Level Tokens: gere um token com o âmbito 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 com Ligar

O token de configuração roda a cada utilização. O Control Center guarda o valor rodado à medida que avança, pelo que nunca tem de o colar outra vez.

Opção B: criá-la no Slack, pré-preenchida

A mesma aplicação, sem token de configuração — o Slack abre-lhe o seu próprio ecrã de criação com todo o manifesto já preenchido.

1. No Control Center, vá a Definições → Espaço de trabalho → Geral e desloque-se até ao cartão Pontes de chat
2. No bloco do Slack, clique em Criar a aplicação para mim
3. Ajuste o nome da aplicação, o nome do bot, as descrições e o comando slash — estes viajam com a ligação
4. Clique em Criar no Slack. O seu navegador abre a página de criação de aplicações do Slack com a configuração pré-preenchida
5. Escolha o espaço de trabalho do Slack e confirme. Os âmbitos, os eventos, o Socket Mode e o comando slash já estão corretos
6. De volta ao Control Center, siga os dois passos restantes que a caixa de diálogo mostra:
   • Basic Information → App-Level Tokens: gere um token com o âmbito 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 com Ligar

O Slack não informa qual foi a aplicação que criou, pelo que o Control Center não fica a saber o id da aplicação e as ligações do passo 6 vão para a sua lista de aplicações em vez de irem diretamente para essa aplicação. Personalizar o bot precisa de um token de configuração.

Opção C: construir a aplicação por si mesmo

Crie uma aplicação em api.slack.com/apps e configure-a da seguinte forma.

Socket Mode: ative-o e deixe todos os URLs de pedido vazios. O Slack recusa um manifesto que peça ao mesmo tempo Socket Mode e entrega por webhook.

Âmbitos do token do bot (OAuth & Permissions):

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

Subscrições de eventos (eventos do bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

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

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

App Home: ative o separador Messages e deixe-o editável, para que os membros possam enviar mensagens diretas ao bot.

Tokens: gere um token ao nível da aplicação com connections:write, depois instale a aplicação e copie o token OAuth do utilizador do bot.

Ligar

1. Vá a Definições → Espaço de trabalho → Geral e desloque-se até ao cartão Pontes de chat
2. No bloco do Slack, clique em Ligar Slack
3. Preencha os campos:

Campo	Valor	Onde se encontra no Slack
Token OAuth do utilizador do bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Token ao nível da aplicação	xapp-…	Basic Information → App-Level Tokens (connections:write)
Token de renovação da configuração da aplicação (opcional)	xoxe-…	O par de tokens de configuração da aplicação em api.slack.com/apps

O prefixo de cada valor é verificado dos dois lados antes de se enviar seja o que for, pelo que um valor colado na caixa errada é recusado com a mesma frase de qualquer das formas.

4. Clique em Ligar

O Control Center verifica o token do bot com o auth.test do Slack antes de guardar seja o que for, pelo que um erro de escrita lhe é comunicado a si em vez de se tornar um socket que nunca funciona em silêncio. O token ao nível da aplicação só pode ser comprovado abrindo o socket, pelo que um token errado aparece um momento depois como um erro de ligação na mesma linha.

Sem o token de configuração da aplicação opcional, a ligação funciona bem — simplesmente não pode editar o bot a partir do Control Center.

O que a ligação faz

• Guarda as credenciais no diretório próprio do espaço de trabalho, ao lado da sua base de dados, legíveis apenas pelo proprietário. Nunca voltam para um cliente
• Abre uma ligaçã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 todas as threads do Slack que já tinham sido ligadas, para que uma reconexão continue as conversas existentes em vez de as deixar penduradas
• Não custa nada aos espaços de trabalho sem aplicação de chat: sem socket, sem temporizadores, sem tráfego

Onde ficam os tokens e porque não no keychain

As credenciais do bot são um ficheiro JSON simples por fornecedor em <dataDir>/<workspaceId>/chat_credentials/, escrito de forma atómica e com permissões restritas ao proprietário. Isto é deliberado, não um descuido: eliminar um espaço de trabalho desvincula esse diretório, pelo que os seus tokens vão com ele, e workspace.export e as cópias de segurança copiam workspace.db — não o diretório —, pelo que um espaço de trabalho que entregue a outra pessoa nunca transporta tokens de bot ativos lá dentro. O corolário é que restaurar um espaço de trabalho noutro sítio implica voltar a ligar o Slack lá.

O acesso à ponte é a pertença ao espaço de trabalho, nunca a posse de um token. Uma conta do Slack tem de estar associada a um utilizador do Control Center que seja membro com um papel de escrita. Ligar, desligar, a configuração guiada, a ligação de configuração e a personalização do bot estão todos reservados a administradores.

Verificar

A linha do Slack mostra uma etiqueta de estado: Ativo, A ligar…, Erro de ligação (com o próprio erro do Slack ao lado), ou Não ligado. 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. Aparece uma resposta em thread no Slack e aparece um espaço correspondente no Control Center

Todos os membros que queiram usar a ponte associam depois a sua própria conta — consulte Associar a sua conta do Slack.

Como é uma resposta no Slack

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

O cartão começa no momento em que o bot aceita a menção — Working on it… —, para que a thread do Slack não fique silenciosa enquanto o espaço de trabalho ainda está a ser construído. A sua primeira menção num canal do Slack cria a conversa, que clona os repos em que o agente trabalha, pelo que essa linha de preparação passa então a dizer Cloning acme/widgets…, depois Setting up Reviewer…, depois Starting the agent…, e depois uma linha Thinking… quando o agente está realmente a raciocinar. Num repositório grande, essa primeira preparação demora algum tempo; o cartão é a forma de perceber que está a trabalhar em vez de o ignorar. As menções seguintes na mesma thread do Slack continuam a abrir com Working on it… e depois saltam os passos de clonagem, porque o espaço de trabalho já existe.

O raciocínio como uma parede de texto e a saída das 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 na aplicação para computador — a ligação aponta para o seu próprio servidor do Control Center, que entrega o navegador à aplicação.

Se não acontecer nada quando clica, o servidor que enviou a mensagem não está acessível a partir da máquina onde clicou (um servidor apenas em loopback clicado a partir de um telemóvel, por exemplo), ou o Control Center não está a correr lá. Um servidor sem endereço acessível envia um cartão sem botão em vez de um que não leva a lado nenhum.

Renovar um token

Volte a colar o novo valor na caixa de diálogo de ligação e clique em Ligar. Ligar substitui a ligação que estivesse a correr para este espaço de trabalho, pelo que o socket é restabelecido com as novas credenciais.

Os dois tokens obrigatórios têm de estar presentes em cada ligação. O token de configuração da aplicação opcional mantém o valor guardado quando deixa a caixa vazia, pelo que renovar um token de bot nunca lhe custa a capacidade de editar a aplicação.

Desligar

Clique em Desligar na linha do Slack (apenas administradores). O socket fecha e as credenciais são esquecidas.

As associações de espaços e de utilizadores sobrevivem deliberadamente: voltar a ligar a mesma aplicação restaura todas as threads do Slack ligadas. São linhas próprias do espaço de trabalho, pelo que eliminar o espaço de trabalho as remove de qualquer forma.

Resolução de problemas

A linha diz «Erro de ligação»

Leia o erro apresentado ao lado da etiqueta. Uma credencial rejeitada (invalid_auth, not_authed, token_revoked, account_inactive) é terminal — a ponte deixa de tentar e aguarda novos tokens, porque tentar para sempre um token revogado só lhe rende um limite de pedidos. Volte a colar os tokens na caixa de diálogo de ligação.

Um erro missing_scope significa que a aplicação está instalada com menos âmbitos do que a ponte precisa. Acrescente o âmbito em falta, reinstale a aplicação no Slack e volte a ligar.

Tudo o que seja transitório (um socket perdido, uma falha momentânea do Slack) volta a ligar-se sozinho com um backoff exponencial limitado a 30 segundos, e a rotação de socket de rotina do Slack não agrava esse backoff.

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

• O bot está no canal? O Slack só entrega mensagens de canal a aplicações que sejam membros. Execute /invite @your-bot-name
• Está associado? Um membro não associado recebe uma resposta nessa thread do Slack a explicar como associar. Consulte Associar a sua conta do Slack
• É membro do espaço de trabalho com um papel de escrita? A um viewer ou guest é dito que o seu papel é só de leitura. A ponte nunca inicia trabalho em nome de alguém que não consegue atribuir
• O espaço de trabalho tem agentes? Sem agentes, a mensagem é guardada mas não há ninguém para lhe responder

Responde num canal mas ignora mensagens simples

Isso é intencional. Fora de uma mensagem direta, a ponte só age sobre uma mensagem que mencione o bot, ou sobre uma resposta dentro de uma thread do Slack que já lhe pertence. Tudo o resto é a conversa de outras pessoas.

As respostas chegam como uma única mensagem grande em vez de em fluxo

A linha diz «O streaming ao vivo está desligado para esta aplicação do Slack — as respostas chegam numa única mensagem.» As respostas em streaming do Slack exigem a funcionalidade Agents & AI Apps num plano pago; quando o Slack a recusa, a ponte deixa de a pedir pelo resto da vida dessa ligação e publica respostas inteiras em vez disso. Não se perde nada — a transcrição completa está sempre no Control Center.

A transmissão em fluxo também precisa de uma âncora de thread do Slack, pelo que uma resposta que não tenha uma thread do Slack onde crescer é publicada inteira. O cartão de tarefa chega de qualquer das formas: numa resposta inteira, viaja na mesma mensagem, já completo.

A resposta não tem cartão por cima

Os cartões de tarefa do Slack fazem parte da mesma superfície nova Agents & AI Apps que a transmissão em fluxo, e o Slack só recusa no momento da chamada. Quando recusa, o Control Center mantém a resposta e descarta o cartão pelo resto da vida dessa ligação — uma resposta sem linha de estado é melhor do que uma linha de estado sem resposta.

«O Control Center precisa de um token de configuração da aplicação para editar o bot»

A linha Personalizar o bot está desativada porque a ligação não tem token de configuração da aplicação. Isto é o esperado numa aplicação criada à mão ou através de Criar no Slack — o Slack nunca disse ao Control Center qual é a aplicação. Gere um par de tokens em api.slack.com/apps e volte a ligar com o token de renovação preenchido.

Uma resposta longa é cortada

O Slack limita uma única mensagem a 40 000 caracteres, pelo que a ponte trunca aos 39 000 e acrescenta um ponteiro para o Control Center — uma resposta encurtada é melhor do que uma que o Slack rejeita de imediato. O texto completo está sempre na transcrição do espaço.

Guias relacionados

• Associar a sua conta do Slack
• Personalizar o bot de chat
• Ponte de chat

Conceitos relacionados

• Pontes de chat