Slack e canais

Um canal tem caminhos diferentes

Slack usa palavras parecidas para coisas diferentes. Configure cada uma no lugar certo.

Caminho	O que usa	Para que serve
Socket Mode	App-level token xapp-...	Receber eventos por WebSocket de saída, sem URL pública
Event Subscriptions	/hooks/channel/<nome>/slack/events	Receber menções e mensagens
Interactivity	/hooks/channel/<nome>/slack	Receber cliques em botões, como aprovação
API do bot	Bot token xoxb-...	Listar canais, postar mensagens e responder threads
Verificação HTTP	Signing secret	Conferir que a chamada HTTP veio do Slack

O signing secret não substitui o app token. O app token não substitui o bot token. Em Socket Mode, o Slack entrega eventos pelo xapp-..., mas postar e listar canais ainda usa o xoxb-....

HTTP callback

Use HTTP quando o Slack consegue alcançar uma URL pública da instalação.

No Slack App:

1. Em Event Subscriptions, informe https://<host>/hooks/channel/<nome>/slack/events.
2. Assine app_mention para menções.
3. Assine message.channels se quiser watched messages em canais públicos.
4. Em Interactivity & Shortcuts, informe https://<host>/hooks/channel/<nome>/slack.
5. Convide o bot para o canal.

Se o Slack disser que a URL não respondeu ao challenge e o log mostrar POST /hooks/channel/<nome>/slack status=400, a URL de eventos foi configurada no endpoint de botões. O endpoint de eventos termina em /events.

Socket Mode

Use Socket Mode quando a instalação não tem URL pública de entrada. O worker abre uma conexão de saída para o Slack.

Você ainda precisa:

• app token xapp-... com connections:write;
• bot token xoxb-...;
• bot dentro do canal;
• eventos assinados no Slack App.

Aprovações por botão continuam precisando do caminho HTTP de Interactivity. Se o Slack não consegue chamar /hooks/channel/<nome>/slack, a plataforma não deve mostrar botões de aprovação no Slack.

Menções

Uma conversa pode nomear o agente que ela inicia. Com um agente escolhido, quem menciona o bot não precisa nomeá-lo, e a frase inteira é a pergunta:

@FuseOneAgent entenda esse alerta

Nessa conversa nenhum outro agente inicia por menção. Mencionar um agente diferente é recusado com o nome do agente da conversa, em vez de rodar outro agente na frase de quem perguntou.

Sem agente escolhido — a opção “nenhum — a mensagem nomeia o agente” — a mensagem precisa começar com o id ou nome do agente, e qualquer agente publicado no escopo da conversa pode ser iniciado:

@FuseOneAgent troubleshooting-sre entenda esse alerta

Nos dois casos a conversa decide o escopo e o texto não escolhe company ou area. O agente só inicia se a versão publicada declara trigger de conversa e existe naquele escopo.

O agente escolhido seleciona, não autoriza. A run continua acontecendo em nome da pessoa cuja conta Slack está vinculada a um usuário da plataforma; quem não tem vínculo continua sendo recusado.

Menções só iniciam agentes nos modos “só menções” e “ambos”. Numa conversa em modo “watched messages”, mencionar o bot é recusado com o motivo — o modo diz que só as fontes configuradas iniciam, e isso vale para as duas formas de entrega.

Uma menção sem nenhuma palavra não inicia nada: @FuseOneAgent sozinho é recusado com uma frase dizendo o que fazer. A exceção é quando a menção chega com algo para trabalhar — uma thread onde a plataforma publicou uma run, ou uma thread cujas mensagens anteriores foram realmente lidas porque “include thread context” está ligado. Estar numa thread não basta: uma thread que ninguém leu deixa o agente tão sem informação quanto uma menção sozinha.

A mesma regra vale para watched messages. Quando a mensagem não tem text próprio, a plataforma lê as palavras dos blocks e attachments — que é como a maioria das integrações de alerta publica — e só recusa quando não encontra nada. A entrega continua gravada inteira, então o payload está lá para conferir.

Watched messages

Watched messages servem para mensagens de um sistema conhecido, como Alertmanager ou Grafana OnCall. A autoridade não vem da mensagem. Ela vem da configuração da conversa:

• qual agente iniciar;
• qual principal é o run as;
• quais Slack user ids, bot ids ou app ids podem disparar.

Use ids estáveis, não display names. Display names mudam; ids são o que o Slack assina.

Thread context

Se “include thread context” estiver ligado, mensagens anteriores da thread entram como input não confiável. Isso ajuda um agente a ler o alerta original quando a menção acontece depois.

Essa opção também inclui mensagens escritas por outras pessoas. Elas podem ser enviadas ao provedor de modelo configurado. Ligue só em canais onde essa consequência foi aceita.

Checklist de diagnóstico

Se o agente não iniciou:

1. O log mostra an ask arrived? Se não, o evento não chegou ao FuseOne.
2. A conversa está no modo certo: menção, watched messages ou ambos? 2b. A menção nomeou um agente diferente do agente escolhido na conversa?
3. O agente publicado tem trigger de conversa?
4. O agente está publicado no mesmo escopo da conversa?
5. Em watched messages, o Slack source id está permitido?
6. O run as existe e tem grant no escopo?
7. Em Socket Mode, o app token está salvo e o worker está conectado?

Conversas de chamados governados

Escolha Chamados governados quando cada mensagem raiz que casar for um chamado de suporte e a thread for o histórico dele. Isso é diferente de uma watched message: quem escreveu precisa ter conta FuseOne vinculada, vira o solicitante imutável, e só essa pessoa pode revisar os campos pedidos.

A conversa pede um agente, um principal de run as, um bot ou app exato que pode nomear destinatários e de um a oito padrões RE2 de admissão. Os padrões são comparados somente com texto limitado da mensagem raiz. Respostas são encontradas pela origem Slack armazenada e nunca são classificadas outra vez pelo texto.

A fonte de endereçamento pode responder com menções do Slack para escolher quem recebe a aprovação. Esses nomes não concedem poder: são intersectados com quem ainda pode executar approval:act no escopo do chamado, e o botão confere a permissão novamente. O card é publicado sob a mensagem raiz e enviado por DM somente aos destinatários nomeados que passaram pela conferência.

Quando um bot escreve a raiz

Em canal de ajuda com formulário, a mensagem raiz é do bot que publica o formulário e o time dono do pedido só é dito depois, na thread. Escolha então “Como o ticket abre” → Marcação na thread.

Nesse modo a conversa pede uma coisa a mais: a fonte que posta a raiz, o id exato do bot ou app do formulário. Os padrões deixam de ser comparados com a raiz e passam a ser comparados com as respostas — a primeira que casar abre o ticket. Quem pode marcar é o bot de endereçamento configurado ou qualquer pessoa do canal; outro bot é ignorado, para que uma integração que ecoa a marcação não abra trabalho.

O ticket fica com a identidade da raiz: o pedido é o texto dela, o solicitante é a pessoa mencionada na primeira linha dela, e toda resposta seguinte cai nesse mesmo ticket. O formulário precisa renderizar o solicitante ali: uma menção abaixo da primeira linha é texto digitado por quem preencheu e nunca diz quem pediu. A menção é evidência, não autoridade — é resolvida contra as contas vinculadas nessa conexão, e uma thread cujo solicitante não resolve não vira ticket. Se a raiz for de outra fonte que não a configurada, a marcação não abre nada.

Ler a raiz é uma chamada ao Slack na hora de abrir: o app precisa do escopo de histórico do canal, o mesmo que o contexto de thread usa. Sem ele a thread fica esperando e nenhum ticket abre.

A sala onde a resposta é revisada

Quando os tickets desta conversa devem ser trabalhados longe de quem pediu, aponte Sala de revisão para outra conversa do mesmo workspace — por convenção, um canal só do time.

Ao abrir o ticket, o bot abre uma thread nessa sala dizendo que chegou um chamado e linkando a thread original. A partir daí tudo acontece lá: o card de decisão é publicado nessa thread e em nenhum outro lugar, nem na thread do chamado nem em outra conversa do escopo. Quem tem Aprovador no escopo corrige respondendo na sala — qualquer um deles, não só quem foi endereçado — e cada correção é uma revisão: a aprovação pendente é cancelada e o agente reescreve. Aprovado, o texto é publicado na thread do chamado e a sala recebe uma linha dizendo que foi.

Na thread do chamado, o que o solicitante escrever é guardado no pedido e não dispara nada: quem manda regerar é a sala. Se houver decisão pendente, a mensagem é registrada e não entra — uma revisão escrita nessa hora substituiria o card que alguém está lendo, sem nada regerar no lugar. Quem não decide pode conversar na sala sem disparar nada, e endereçar aprovadores por menção não vale aqui: a sala é o endereço.

Publicar uma resposta encerra aquela revisão, não o chamado. A revisão aprovada fica registrada com o texto que saiu, e o ticket volta a aceitar correção: a próxima coisa que o solicitante disser é sobre o mesmo pedido, na mesma thread. O chamado termina quando alguém com Aprovador no escopo reage à mensagem do chamado com um dos emojis configurados em Emoji que encerra o chamado. Reaction de quem não decide é ignorada em silêncio, reaction retirada não reabre nada, e se houver resposta esperando aprovação na hora do fechamento ela é cancelada e a sala recebe uma linha dizendo que não foi publicada. Fechado, o chamado não aceita mais nada — nem correção na sala, nem contexto na thread. Enquanto não fecha, ele continua contando na cota de tickets abertos da área.

Para o agente propor a resposta, declare a ferramenta $fuseone.ticket.answer nele. Ela é um efeito de escrita: o agente chama com o texto, o Gate para o run, e o card na sala carrega exatamente aquelas palavras. Aprovado, o texto é selado como desfecho do ticket e publicado na thread do chamado; a sala recebe a confirmação. Se o agente reescrever a resposta depois do card, a publicação é recusada — a aprovação é sobre o texto que a pessoa leu. Uma resposta aprovada conclui o ticket.

Enquanto a thread da sala não existe, os cards esperam: nada cai na thread do chamado por falta de lugar. O bot precisa estar na sala, senão o ticket fica parado aí — o worker registra a falha e tenta de novo.

Para a configuração completa do Gravitee e a sequência de validação, veja Chamados governados no Gravitee.

Uma sala para a instalação inteira

Uma conversa recebe os runs do escopo em que foi configurada, e uma configurada numa empresa cobre todas as áreas dela. Sobra o caso de uma área que ninguém apontou para canal nenhum: um run parado ali não produz card nem mensagem privada, e fica esperando alguém abrir o console.

Em Integrações → Canais → nova conversa, o contexto “A instalação inteira” resolve isso. Ela ouve sobre um run de qualquer empresa, com as mesmas opções de sempre — inclusive avisar em particular quem pode decidir, que continua alcançando quem tem Aprovador no escopo daquele run, e não quem tem grant na instalação.

Ela não inicia nada. Mencionar o bot ali é recusado dizendo que a sala só relata, e nenhuma automação de watched message parte dela. Escopo que contém tudo é a resposta certa para ouvir e a errada para pedir: uma sala que ouve todas as empresas é uma configuração razoável, e uma que pode iniciar um agente em todas elas é outra coisa inteiramente.

Por isso o contexto só aparece para quem governa a instalação — quem tem Configurador de empresa concedido no escopo da instalação. Configurar para onde uma área relata é um ato escopado comum; decidir que uma sala ouve todas as empresas é a autoridade acima delas. O mesmo vale para apagá-la.

Comece pelo “o que avisar”. O padrão é parada, falhou e fora do combinado, e nesse escopo isso significa toda parada, toda falha e todo drift de toda empresa — o volume de uma sala dessas é a soma de todas as outras. Estreite antes de salvar.

Avisar em particular quem pode decidir

Uma conversa avisada sobre runs parados pode, além do card no canal, mandar o mesmo pedido por mensagem direta do bot para quem pode decidir. Ligue em Integrações → Canais → a conversa → “Também avisar em particular quem pode decidir”.

Quem recebe são as pessoas com o papel Aprovador num escopo que contém o run — não administradores, que podem decidir e seriam avisados de todo run parado da instalação inteira. Cada uma precisa de conta Slack vinculada; quem não tem simplesmente não é alcançado.

A DM endereça e não autoriza. O botão é checado contra o escopo do próprio run onde quer que seja apertado, então quem não tem o grant é recusado numa mensagem privada igual a como seria no canal.

Ela também não substitui o canal. O card no canal vai primeiro, e uma conversa que não pôde ser avisada não é respondida com uma mensagem privada no lugar — o ledger registra toda decisão, mas a visibilidade que faz alguém reparar que um run está parado há duas horas está no canal.

Precisa do escopo im:write no app do Slack. Sem ele a DM é recusada, a falha fica registrada e o canal continua sendo avisado normalmente.

Se mais de vinte pessoas puderem decidir, ninguém recebe DM e a razão é registrada. Avisar vinte arbitrárias de cem é pior que avisar nenhuma: ninguém consegue dizer quem era para ter sido perguntado.

Cards que já foram respondidos

Depois que alguém decide, todo card daquele passo é reescrito dizendo o que aconteceu e quem decidiu, e os botões somem. Vale para o card do canal também, então uma aprovação decidida no console não deixa mais botões vivos por lá.

Um card que não pode ser reescrito — mensagem apagada, conversa removida — é marcado como fechado mesmo assim, para não consumir a varredura para sempre.