# Slack e canais

Conecte o Slack a um projeto e controle sessões por um canal.

Canonical page: https://beeuni.ai/docs/pt/connect/slack

Um canal conecta uma plataforma de chat a um projeto. Uma mensagem em um canal conectado inicia uma [sessão](/docs/pt/work/sessions). O agente responde na mesma thread.

<a id="live-channels"></a>

## Canais disponíveis

Atualmente, o Beeuni é compatível com quatro plataformas de canal:

- **Slack** — conecte com um clique pelo app gerenciado pelo Beeuni ou use seu próprio token de bot.
- **Microsoft Teams** — conecte por OAuth com consentimento do administrador da organização ou use seu próprio Azure Bot (experimental; ative em [Settings → Feature flags](/docs/pt/feature-flags)).
- **Email** — um canal com tecnologia AgentMail (experimental; ative em [Settings → Feature flags](/docs/pt/feature-flags)).
- **Voz** — um canal de voz em tempo real (experimental; ative em [Settings → Feature flags](/docs/pt/feature-flags)). Converse com um agente em tempo real.

A conexão pelo CLI e pelo painel só está disponível para Slack e Microsoft Teams. Email e voz são gerenciados pelo painel. Esta página aborda o Slack. O Teams segue as mesmas regras de sessão, vinculação de identidade e credenciais.

<a id="how-a-channel-starts-a-session"></a>

## Como um canal inicia uma sessão

A primeira mensagem em uma thread do Slack ou conversa do Teams cria uma sessão. A thread mantém essa sessão mesmo depois que o sandbox para e é retomado.

Em um canal do Slack, uma mensagem posterior só chega à sessão quando menciona o bot. Respostas sem marcação são destinadas às pessoas na thread. O agente as lê na próxima vez que alguém o mencionar. Em uma mensagem direta, todas as mensagens vão para a sessão.

Um workspace do Slack conectado a mais de um projeto mostra um seletor de projeto na primeira menção.

<a id="identity-linking"></a>

## Vinculação de identidade

Antes de o agente atuar, o Beeuni vincula cada remetente do chat a uma conta do Beeuni. Execute `/beeuni login` no Slack e siga o link para entrar. O Teams exige o mesmo. Um remetente sem vínculo recebe uma solicitação para vincular a conta, em vez de iniciar uma sessão.

Um link de entrada só funciona uma vez e expira após 10 minutos. Uma conta do Slack conectada a uma conta do Beeuni não pode ser conectada a outra: execute `/beeuni logout` primeiro. Se sua organização exigir autenticação de dois fatores, o Beeuni solicitará seu segundo fator antes de conectar você, e o chat será executado com o fator usado na conexão.

Cada ação é executada como a conta vinculada da pessoa que a realizou, com a função dessa conta no projeto. Proprietários e administradores da conta são considerados gerentes do projeto.

| Ação | Quem pode realizá-la |
|---|---|
| Mencionar o bot em uma nova mensagem ou na thread dele | Uma conta vinculada com acesso ao projeto, dentro da política do canal |
| Interromper uma execução | A pessoa que enviou a mensagem respondida ou qualquer pessoa aprovada para participar da sessão, desde que ainda possa usar o projeto |
| Alterar o projeto, agente, modelo ou política do canal | Um gerente do projeto; em uma mensagem direta com o bot, qualquer membro do projeto |
| Tomar uma decisão sobre uma revisão | Um gerente do projeto |
| Aprovar ou negar uma chamada de conector | Um gerente do projeto ou a pessoa que iniciou a sessão |
| Aprovar alguém para participar de uma thread `owner_approval` | O proprietário da sessão |
| `link-bot` | Um gerente do projeto |

<a id="where-credentials-live"></a>

## Onde ficam as credenciais

O token de bot de um canal conectado é um [segredo](/docs/pt/project/secrets) com escopo de conector. Ele não aparece na página Secrets do projeto. O Beeuni nunca o injeta em um sandbox. O Beeuni resolve o token no servidor quando o agente envia ou lê uma mensagem de chat.

<a id="connect-slack"></a>

## Conectar o Slack

### Inicie a conexão
No CLI, execute:

```
beeuni channels connect
```

Em um host com o app compartilhado do Slack configurado (como o Beeuni Cloud), esse comando exibe um link de instalação com um clique. Abra o link e escolha o workspace. Clique em **Allow**. Adicione `--wait` para que o comando continue verificando até a instalação ser concluída.

No painel, abra a página Channels do projeto e conecte o Slack por lá. O fluxo de instalação é o mesmo.

<a id="use-your-own-slack-app"></a>

### Usar seu próprio app do Slack

Para usar seu próprio app do Slack, execute `beeuni channels manifest` para exibir um manifesto do app. Crie o app em `api.slack.com/apps` usando esse manifesto. Instale o app no workspace. Em seguida, execute:

```
beeuni channels connect --manual --bot-token xoxb-... --signing-secret ...
```

### Verifique a conexão
```
beeuni channels status
```

Execute `beeuni channels disconnect` para remover a conexão. Consulte a [referência do CLI](/docs/pt/cli) para ver todas as opções.

Ao conectar o Slack, uma entrada de [conector](/docs/pt/connect/connectors) `channel` é adicionada a `beeuni.yaml` para você. Você nunca precisa escrever essa entrada manualmente.

<a id="use-slack"></a>

## Usar o Slack

Mencione o bot com uma tarefa em qualquer canal ao qual ele tenha sido adicionado ou abra uma mensagem direta. Como descrito acima, a thread mantém sua sessão. Mencione o bot novamente em uma thread de canal para dar continuidade. Se você apenas mencionar o bot, sem uma tarefa, receberá um lembrete para adicionar uma, em vez de iniciar uma sessão.

<a id="what-the-agent-can-read"></a>

## O que o agente pode ler

O agente lê o Slack pelo [conector](/docs/pt/connect/connectors) do Slack do projeto (`beeuni_slack` ou pelo comando `slack` no sandbox). Todos os projetos conectados ao mesmo workspace do Slack usam o mesmo bot. Por isso, o Beeuni mantém cada leitura dentro das conversas do próprio projeto:

| Conversa | Leitura |
|---|---|
| Um canal ou uma mensagem direta conectado a este projeto | Permitida |
| Uma thread iniciada ou integrada por uma sessão deste projeto, em qualquer canal | Permitida |
| Um canal, mensagem direta ou thread de outro projeto | Recusada |
| Uma conversa não conectada a nenhum projeto | Permitida somente enquanto nenhum outro projeto estiver conectado ao workspace |

Uma leitura recusada responde `403` com o motivo `conversation_not_in_project` e uma mensagem que identifica a conversa. Para ler uma conversa que não esteja conectada a nenhum projeto, conecte-a primeiro: execute `/beeuni switch` nela e escolha este projeto.

- O histórico do canal não inclui as mensagens de uma thread de outro projeto.
- `get_history` e `get_thread` adicionam `user_name` a cada mensagem cujo autor o Slack consiga identificar, ao lado do ID `user`. Até 25 pessoas são identificadas por leitura; um nome que o Slack não retornar em até 2 segundos será omitido.
- `list_channels` lista todos os canais públicos e os canais privados e as mensagens diretas que o agente pode ler.
- `channel_info` responde para qualquer canal público. Para um canal privado ou mensagem direta, aplica-se a tabela acima.
- `file_info` responde quando o arquivo é compartilhado em uma conversa que o agente pode ler ou em uma thread deste projeto. `slack download` segue a mesma regra: se um arquivo for compartilhado somente em uma conversa de outro projeto, a resposta será `403`. O download é interrompido em 50 MB e responde `413`.
- `search_messages` só é executado enquanto nenhum outro projeto estiver conectado ao workspace, pois uma busca não pode ser limitada às conversas de um único projeto.
- `list_users`, `user_info` e `auth_test` leem o diretório do workspace e não têm restrições.

As gravações seguem a regra própria descrita abaixo.

<a id="what-the-agent-can-post"></a>

## O que o agente pode publicar

Publicar, enviar um arquivo, editar, excluir, reagir, entrar em um canal e vincular uma thread seguem a mesma regra: o agente nunca atua dentro do canal ou da thread de outro projeto.

| Destino | Gravação |
|---|---|
| Um canal deste projeto ou uma thread iniciada ou integrada por uma das sessões do projeto | Permitida |
| Um canal não conectado a nenhum projeto | Permitida. Uma nova mensagem inicia a thread deste projeto, então uma resposta que mencione o bot retorna à sessão |
| Uma mensagem direta com uma pessoa | Permitida, inclusive quando a mensagem direta dessa pessoa com o bot executa outro projeto |
| Um canal ou uma mensagem direta em grupo de outro projeto | Recusada |
| Uma thread de outro projeto, em qualquer conversa | Recusada: não pode responder, editar, excluir nem reagir |

Uma gravação recusada responde `403` com o motivo `conversation_not_in_project` e uma mensagem que identifica a conversa. `slack send --file` e `slack bind-thread` seguem a mesma regra.

`channel` deve ser o ID da conversa ou do usuário, como `C0123ABCD` ou `U0123ABCD`, e não o nome do canal. O Slack publica em um nome, que não pode ser verificado de acordo com a regra. Se, ainda assim, o Slack publicar uma mensagem em qualquer lugar que não seja a conversa verificada, o Beeuni excluirá a mensagem e recusará a publicação.

Para publicar em um canal gerenciado por outro projeto, execute `/beeuni switch` nele e escolha este projeto, ou publique pelo outro projeto.

<a id="control-a-session-with-slash-commands"></a>

## Controlar uma sessão com comandos de barra

Digite estes comandos como `/beeuni <command>` no Slack ou como texto simples em uma mensagem direta. Os comandos de barra não são executados no painel de mensagens diretas do Assistant, então o Beeuni interpreta as mesmas palavras como texto simples nesse painel.

| Comando | O que faz |
|---|---|
| `login`, `logout` | Vincula ou desvincula sua identidade do Slack |
| `switch`, `unbind` | Vincula novamente ou desvincula este canal do projeto |
| `projects` | Lista os projetos aos quais você pode vincular o canal |
| `sessions` | Lista as sessões recentes iniciadas neste workspace |
| `whoami` | Exibe o painel do canal: projeto, agente, modelo, política e sua identidade vinculada |
| `models` | Escolhe o modelo para este canal — consulte [Modelos e chaves](#models-and-keys) |
| `agent <name>`, `model <id>` | Define o agente ou modelo usado por este canal |
| `policy <mode>` | Define quem pode iniciar sessões aqui |
| `help` | Lista todos os comandos |

`policy` aceita `project_open` (padrão — qualquer membro do projeto que mencione o bot inicia uma sessão), `owner_approval` ou `owner_only`. Esta configuração se aplica a um recurso de um canal específico; não é uma função. Ela não concede permissões que o resultado da função negue — consulte [Contas e acesso](/docs/pt/accounts#per-feature-access-settings).

<a id="models-and-keys"></a>

## Modelos e chaves

`/beeuni models` lista todos os modelos que você pode usar aqui, como faz o seletor da Web: modelos do Beeuni e modelos acessados por uma chave de API de provedor ou uma assinatura do ChatGPT. Cada modelo informa como é pago. Uma lista longa aparece em um único seletor no qual você pode digitar. Escolha um modelo ou digite `/beeuni model <id>`; `/beeuni model default` retorna ao padrão do projeto.

As chaves disponíveis dependem da conversa:

- **Uma mensagem direta com o bot** — suas próprias chaves e assinatura do ChatGPT, além das chaves compartilhadas com o projeto. As sessões são privadas para você.
- **Um canal ou uma mensagem direta em grupo** — somente as chaves compartilhadas com todo o projeto. Em vez disso, escolha em uma mensagem direta um modelo que use suas próprias chaves.

Um modelo que usa chaves utiliza todas as chaves que você pode usar para o provedor, alternando entre elas quando os limites de uso são atingidos. O modelo do canal inicia cada nova thread; uma thread mantém o modelo com que foi iniciada. Se um modelo deixar de estar disponível para uma thread, ele será substituído somente nessa mensagem, em vez de a mensagem falhar. Consulte [Chaves de provedores e acesso de membros](/docs/pt/project/models#provider-keys-and-member-access).

Uma mensagem de continuação com imagem é executada em um modelo capaz de ler imagens. Se nenhum modelo disponível puder fazer isso, o agente será informado no prompt: ele dirá que não consegue ver a imagem e pedirá o texto, em vez de tentar adivinhar.

<a id="channel-and-people-names"></a>

## Nomes de canais e pessoas

O Slack envia IDs, como `C0123ABCD` e `U0123ABCD`. O Beeuni exibe os nomes que as pessoas veem no Slack e mantém os IDs para as operações.

| Onde | O que exibe |
|---|---|
| A página Channels, `beeuni channels bindings` | `#channel` para um canal público ou privado, a pessoa em uma mensagem direta, os membros em uma mensagem direta em grupo |
| Uma mensagem do Slack em uma sessão | O nome do remetente e `#channel` |
| Uma resposta `slack send` em uma sessão | `#channel` ou a pessoa em uma mensagem direta |
| O título da sessão | Menções como o Slack as exibe: `@Beeuni`, não `<@U0123ABCD>` |
| O prompt do agente | Nomes ao lado dos IDs: `Sam Rivera (U0123ABCD)`, `#general (C0123ABCD)` |
| As etapas do plano do agente no Slack | Uma pessoa como `@Sam Rivera`, um canal como `#general`. Uma etapa nunca notifica ninguém |
| Um cartão de aprovação no Slack | Um parâmetro de canal como link do canal, que o Slack nomeia conforme seu próprio acesso. Um parâmetro de usuário com o nome da pessoa |

Se o Slack não encontrar um canal, ele aparecerá como **Canal indisponível** e manterá o ID. Isso acontece quando o canal foi excluído ou o bot foi removido dele. Um nome que o Slack não retornar em até 2 segundos será omitido dessa mensagem. O prompt incluirá somente os IDs, e a resposta não aguardará.

<a id="approvals"></a>

## Aprovações

Quando o agente precisa de uma decisão humana antes de prosseguir, ele cria um item de revisão. Se a sessão foi iniciada nesta thread, a decisão aparece aqui em um cartão com título, resumo, nível de risco e as opções **Approve**, **Request changes** e **Deny**.

**Request changes** abre um campo para informar o que deve ser alterado. O que você digitar será armazenado junto com a decisão e enviado ao agente, para que ele não precise perguntar novamente. É opcional — se você enviar o campo vazio, o agente receberá instruções para perguntar. Aprovar e negar continuam sendo ações de um clique.

Para tomar uma decisão sobre uma revisão, é necessário ter uma conta do Beeuni vinculada com acesso de gravação ao projeto.

<a id="stopping-a-run"></a>

## Interromper uma execução

Enquanto o agente trabalha, a mensagem ao vivo exibe um botão **Stop**. Ele encerra a execução no runtime, não apenas na mensagem — uma execução que permanece aberta absorve a próxima mensagem da thread em vez de respondê-la.

A execução pode ser interrompida pela pessoa que enviou a mensagem respondida ou por qualquer pessoa aprovada para participar dessa sessão, desde que ainda possa usar o projeto. Quem estiver apenas acompanhando o canal não poderá interrompê-la e receberá uma mensagem privada informando isso.

<a id="what-does-not-work"></a>

## O que não funciona

- Os comandos de barra não são executados no painel de mensagens diretas do Assistant. Digite `/beeuni <command>` como texto simples nesse painel.
- Outras plataformas de chat, incluindo Telegram, ainda não são compatíveis como canais. A conexão pelo CLI e pelo painel só está disponível para Slack e Microsoft Teams; email e voz são conectados pelo painel.