Ligue o Slack ao seu espaço de trabalho

O que vai construir

No final deste tutorial, terá:

• Uma aplicação do Slack criada para o seu espaço de trabalho, com as permissões e os eventos certos já definidos
• Uma ligação ativa entre o Slack e o Control Center
• A sua própria conta do Slack associada ao seu utilizador do Control Center
• Um agente a responder-lhe numa thread do Slack e um ticket aberto a partir de um comando slash

Pré-requisitos:

• O seu primeiro espaço de trabalho e Despache o seu primeiro agente concluídos — um espaço de trabalho sem agentes pode receber uma mensagem do Slack, mas não tem ninguém para a responder
• O agente CEO do espaço de trabalho tem um adaptador e um modelo definidos em Definições → Espaço de trabalho → Agentes. A ponte desperta o CEO, não o agente que configurou no tutorial anterior, e um agente sem adaptador é executado no ciclo integrado com o modelo predefinido da Anthropic.
• O papel owner ou admin no espaço de trabalho do Control Center (ligar uma aplicação de chat fala em nome de todo o espaço de trabalho)
• Permissão para criar e instalar aplicações no seu espaço de trabalho do Slack

Nada aqui precisa de um endereço público, de um túnel nem de uma porta de entrada. O Control Center liga-se para fora ao Slack através do Socket Mode, por isso isto funciona a partir de um portátil atrás de NAT.

Passo 1: Obter um token de configuração da aplicação do Slack

Este é o único segredo que tem de ir buscar à mão. Permite que o Control Center crie e mais tarde edite a aplicação por si.

1. Abra api.slack.com/apps
2. Desloque-se até à secção dos tokens de configuração da aplicação, na parte inferior da página
3. Gere um par de tokens para o seu espaço de trabalho do Slack
4. Copie o token de renovação — começa por xoxe-

Passo 2: Deixar o Control Center criar a aplicação

1. No Control Center, vá a Definições → Espaço de trabalho → Geral e encontre o cartão Pontes de chat
2. No bloco Slack, clique em Criar a aplicação para mim
3. Cole o token de configuração da aplicação
4. Reveja o aspeto que o bot vai ter:
   • Nome da aplicação: como o Slack lista a aplicação, por exemplo Control Center · Acme
   • Nome do bot: o que as pessoas escrevem depois de @, por exemplo control-center
   • Descrição curta e O que o bot diz que sabe fazer
   • Comando slash: cc por predefinição, por isso o comando é /cc
   • Mensagens diretas: deixe ativado para que os membros possam enviar mensagens diretas ao bot
5. Clique em Criar aplicação

O Control Center compõe toda a definição da aplicação — Socket Mode ativado, os âmbitos do bot e as subscrições de eventos de que precisa, o comando slash, o separador Messages — e cria-a no Slack.

Passo 3: Concluir os dois passos que só o Slack consegue fazer

O Slack não tem API para gerar um token de nível de aplicação nem para instalar uma aplicação, por isso a caixa de diálogo entrega-lhe ambos como ligações:

1. Gerar um token de aplicação — abre Basic Information → App-Level Tokens. Crie um token com o âmbito connections:write e copie-o. Começa por xapp-
2. Instalar a aplicação — abre Install App. Instale-a no seu espaço de trabalho e copie depois o Bot User OAuth Token. Começa por xoxb-

Guarde os dois valores para o passo seguinte.

Passo 4: Ligar

1. De volta à caixa de diálogo, clique em Colar as credenciais
2. Introduza o Token do bot (xoxb-…) e o Token de aplicação (xapp-…)
3. Deixe o Token de configuração da aplicação vazio — o do passo 1 já está guardado (o Slack rodou-o e o Control Center guardou o novo)
4. Clique em Ligar

O Control Center verifica o token do bot junto do Slack antes de guardar seja o que for e só depois abre o socket. A linha passa a mostrar o nome do bot e o nome do seu espaço de trabalho do Slack com uma etiqueta Ativo.

Passo 5: Associar a sua própria conta do Slack

A ligação torna o bot alcançável; a associação torna o utilizador reconhecível. Enquanto a sua identidade do Slack não estiver associada, o bot não atuará sobre as suas mensagens — nunca atribui uma mensagem a quem instalou a aplicação.

A associação é pessoal, por isso fica numa página diferente da ligação de todo o espaço de trabalho.

1. Vá a Definições → Espaço de trabalho → Perfil e identidade e encontre o cartão Contas de chat vinculadas
2. Clique em Vincular minha conta do Slack
3. Copie o comando que aparece, por exemplo /cc link K7M2QP
4. No Slack, envie esse comando ao bot numa mensagem direta
5. O bot responde «Linked — you are …»

O código é de uso único e expira em 15 minutos. Se o seu email do Slack corresponder a um utilizador do Control Center que já é membro deste espaço de trabalho, a ponte associa-o automaticamente na primeira vez que falar com ela, e pode saltar este passo.

Se mencionar o bot antes de isto estar feito, ele recusa e diz porquê. As três recusas são distintas, por isso veja qual delas recebeu:

• Remetente não associado: o bot explica-lhe como associar a conta. Volte a este passo.
• Associado, mas não é membro deste espaço de trabalho: peça a um administrador que o convide.
• Membro com um papel só de leitura (viewer ou guest): o bot não inicia trabalho em seu nome.

Passo 6: Encarregar um agente de algo

1. No Slack, convide o bot para um canal: /invite @control-center

2. Mencione-o com um pedido real:

   @control-center resuma as PRs abertas no repo api

A ponte:

1. Cria um espaço do Control Center para essa thread do Slack, com o nome do canal do Slack e do seu pedido
2. Desperta o agente de entrada do espaço de trabalho (o agente CEO, quando existe; caso contrário, o primeiro agente)
3. Transmite a resposta do agente de volta para a thread do Slack à medida que é escrita

Responda na mesma thread do Slack para continuar — não são precisas mais menções, porque a thread do Slack está agora ligada pela ponte. Ou envie antes uma mensagem direta ao bot, em vez de usar um canal; cada conversa por mensagem direta conduz o seu próprio espaço do Control Center, com um título e uma linha de estado «is thinking…» enquanto o agente trabalha.

O streaming precisa da API de streaming do Slack, que nem todos os planos têm. Se a sua aplicação não a puder usar, a ponte deixa de tentar durante toda a ligação e publica cada resposta como uma única mensagem, e o cartão Pontes de chat mostra «O streaming ao vivo está desligado para esta aplicação do Slack — as respostas chegam numa única mensagem.». Tudo o resto funciona da mesma forma.

Passo 7: Abrir um ticket sem sair do Slack

/cc ticket Fix the flaky login test | It fails on CI about once a day.

O bot responde com a chave do ticket que abriu. O ticket é um ticket local comum do Control Center, reportado por si, pronto a ser atribuído a um agente. /cc help lista tudo o que o comando consegue fazer.

Resumo

Criou uma aplicação do Slack a partir do Control Center, ligou-a através de um socket de saída, associou a sua identidade do Slack ao seu utilizador do Control Center e conduziu um agente a partir de uma thread do Slack. Tudo o que aconteceu no Slack também existe no Control Center: a thread do Slack é um espaço, a resposta é uma transcrição, o ticket é um ticket.

A seguir: Configurar a integração com o Slack aborda o percurso manual, a rotação de tokens e a resolução de problemas. Para o modelo que está por baixo, leia Pontes de chat.