> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Converse com o ChatCLI pelo Slack via Events API: um endpoint HTTP assinado que o gateway serve, mensagens de voz e imagem recebidas e respostas com imagem.

O Slack entrega eventos num endpoint HTTP, então o gateway roda um pequeno servidor para isso, e o Slack precisa alcançá-lo por HTTPS (um host público, um túnel ou um reverse proxy na frente de `CHATCLI_SLACK_ADDR`). Toda requisição é conferida contra o **signing secret** do app.

| | Slack |
| - | - |
| Transporte | Events API: o Slack envia eventos para um servidor HTTP que o gateway roda |
| Quem pode falar com o bot | Quem consegue postar onde o app recebe eventos `message`; não há lista de usuários |
| Voice notes recebidas | Sim, um arquivo de áudio na mensagem |
| Respostas em voz | Não (só texto) |
| Imagens recebidas | Sim |
| Imagens enviadas | Sim |
| Sinal de "trabalhando" | Um aviso curto em texto se a resposta passar de uns 2 segundos |

## Configuração

<Steps>
  <Step title="Crie o app do Slack">
    Nas configurações de apps do seu workspace, crie um app e dê ao bot os escopos que ele precisa: `chat:write` para responder, `files:read` para baixar arquivos de voz e imagem, `files:write` para respostas com imagem e os escopos de histórico das conversas que ele deve ler (por exemplo `channels:history` e `im:history`). Instale o app no workspace e copie o **Bot User OAuth Token** (`xoxb-…`) e, em Basic Information, o **Signing Secret**.
  </Step>

  <Step title="Configure o ChatCLI">
    ```bash theme={"system"}
    export CHATCLI_SLACK_BOT_TOKEN="xoxb-..."
    export CHATCLI_SLACK_SIGNING_SECRET="..."
    export CHATCLI_SLACK_ADDR=":8081"              # onde o servidor de eventos escuta
    # export CHATCLI_SLACK_PATH="/slack/events"    # o padrão
    ```
  </Step>

  <Step title="Inicie o gateway">
    ```text theme={"system"}
    /gateway start
    /gateway status     # slack deve aparecer
    ```
  </Step>

  <Step title="Aponte o Slack para o endpoint">
    Ligue **Event Subscriptions** e defina a Request URL como o endereço HTTPS público que chega em `CHATCLI_SLACK_ADDR` e `CHATCLI_SLACK_PATH`, por exemplo `https://bot.example.com/slack/events`. O Slack verifica a URL na hora, então o gateway já precisa estar rodando. Inscreva o bot nos eventos `message` das conversas que ele deve atender (por exemplo `message.channels` e `message.im`), salve e convide o bot para um canal ou mande uma mensagem direta para ele.
  </Step>
</Steps>

## Variáveis de ambiente

| Variável | Obrigatória | Padrão | O que faz |
| - | - | - | - |
| `CHATCLI_SLACK_BOT_TOKEN` | sim | — | O token do bot (`xoxb-…`). |
| `CHATCLI_SLACK_ADDR` | sim | — | Endereço do servidor de eventos, por exemplo `:8081`. O adaptador só liga com o token e o endereço definidos. |
| `CHATCLI_SLACK_SIGNING_SECRET` | sim, na prática | — | Verifica toda requisição. Sem ele todo evento é recusado com `401`, inclusive a verificação de URL do Slack, e um aviso é registrado no start. |
| `CHATCLI_SLACK_PATH` | não | `/slack/events` | Caminho do endpoint de eventos. |
| `CHATCLI_SLACK_HOME_CHANNEL` | não | — | Channel ID padrão das [mensagens proativas](/pt/gateway/proactive-messaging) enviadas com `@send slack`. |

## Quem alcança o bot

Cada requisição precisa trazer um `X-Slack-Signature` válido (HMAC-SHA256 da requisição com o signing secret) e um timestamp de no máximo cinco minutos; o resto recebe `401`. Mensagens postadas por bots são ignoradas, então o gateway nunca responde a si mesmo.

<Warning>
  O Slack não tem lista de usuários permitidos: quem pode postar numa conversa que o app escuta pode rodar o agente, com suas tools e o shell. Limite o app aos canais e às pessoas que devem usá-lo.
</Warning>

## Mensagens

* **Texto**: eventos `message`. Menções chegam do mesmo jeito, já que uma menção é uma mensagem; eventos `app_mention` separados não são usados.
* **Voz**: o primeiro arquivo de áudio da mensagem é baixado com o token do bot e transcrito antes de o agente rodar.
* **Imagens**: o primeiro arquivo de imagem da mensagem chega ao modelo.
* **Respostas com imagem** são enviadas pela API de upload de arquivos do Slack, com o texto da resposta como comentário; em qualquer falha o texto é enviado sozinho.
* **As respostas são postadas na conversa**, não numa thread.
* Uma mensagem que traz só outros tipos de arquivo (um PDF, um zip) é ignorada.

## Limites

* Uma resposta é cortada em **3500 caracteres** e termina com `…`.
* Os erros do Slack (por exemplo `not_in_channel`, quando o bot não foi convidado) ficam registrados como envios com falha em `~/.chatcli/gateway.log`.
* O Slack reenvia um evento cujo recebimento não viu confirmado a tempo; um evento reenviado é processado de novo.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O Slack diz que a Request URL não respondeu">
    O gateway precisa estar rodando e alcançável na URL, e `CHATCLI_SLACK_SIGNING_SECRET` precisa estar definido: sem ele a requisição de verificação é recusada com `401`. Procure em `~/.chatcli/gateway.log` o aviso sobre o secret ausente.
  </Accordion>

  <Accordion title="O bot não vê nada num canal">
    Convide o bot para o canal e confira se o app está inscrito no evento `message` daquele tipo de conversa e tem o escopo de histórico correspondente.
  </Accordion>

  <Accordion title="As respostas com imagem chegam só como texto">
    O upload precisa do escopo `files:write`; o gateway volta para texto quando o upload falha.
  </Accordion>
</AccordionGroup>

## Veja também

<CardGroup cols={2}>
  <Card title="Chat gateway" icon="comments" href="/pt/gateway/chat-gateway">
    Como as mensagens rodam, voz, imagens, continuidade e os outros canais.
  </Card>

  <Card title="Mensagens proativas" icon="paper-plane" href="/pt/gateway/proactive-messaging">
    Deixe o agente postar no Slack por conta própria com `@send`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.