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

# Slack

> Configuração passo a passo do canal Slack e envio via API

Guia completo para configurar o canal **Slack** na plataforma e disparar mensagens via API.

## Como o canal funciona

O canal Slack tem **dois modos de operação**, que podem coexistir na mesma configuração:

| | Bot Token (recomendado) | Incoming Webhook (simples) |
| - | - | - |
| DM para usuário por e-mail | Sim (`users.lookupByEmail`) | Não |
| DM para usuário por Slack ID | Sim | Não |
| Envio para canais e grupos | Sim (qualquer canal onde o bot foi convidado) | Só o canal fixo escolhido na criação do webhook |
| Block Kit (mensagens ricas) | Sim | Sim |
| Exige app instalado no workspace | Sim, com os scopes abaixo | Sim, sem scopes adicionais |

**Entrega múltipla:** a mensagem é entregue em **todos os destinos que se aplicarem** na mesma chamada — canal (via `recipient.slack_channel` ou **Canal padrão**) **e** DM (via `recipient.slack_user_id` ou `recipient.email`). O Incoming Webhook é usado quando não há Bot Token, ou como canal fixo adicional quando o envio pelo bot não tem nenhum canal (nem `slack_channel` na chamada, nem Canal padrão). [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) seguem outra regra, com uma entrega por contato — veja [Em campanhas](#em-campanhas).

## Parte 1 — Criar o Slack App

1. Acesse [api.slack.com/apps](https://api.slack.com/apps) e clique em **Create New App → From scratch**.
2. Dê um nome ao app (ex.: `OctaSend`) e selecione o workspace de destino.
3. No menu lateral, abra **OAuth & Permissions → Scopes → Bot Token Scopes** e adicione:
   * `chat:write` — enviar mensagens
   * `users:read` — ler dados de usuários
   * `users:read.email` — encontrar o usuário pelo e-mail (necessário para DM por e-mail)
   * `im:write` — abrir conversas de DM
   * `channels:read` — listar canais públicos
   * `groups:read` — listar canais privados
   * `chat:write.customize` — opcional, para personalizar o nome e o ícone do bot em cada template
4. Ainda em **OAuth & Permissions**, clique em **Install to Workspace** e autorize.
5. Copie o **Bot User OAuth Token** — começa com `xoxb-`.

> [!WARNING]
>
> Para enviar a um canal (público ou privado), o bot precisa ser **convidado ao canal**: digite `/invite @NomeDoBot` dentro do canal no Slack.

### (Opcional) Incoming Webhook

Se quiser o modo simples (canal fixo), no painel do mesmo app:

1. Abra **Incoming Webhooks** e ative a opção.
2. Clique em **Add New Webhook to Workspace**, selecione o canal de destino e autorize.
3. Copie a **Webhook URL** — começa com `https://hooks.slack.com/services/`.

Nesse modo não é preciso configurar scopes: a autorização do webhook já basta.

## Parte 2 — Configurar o canal na plataforma

1. No painel, acesse **Configurações → Canais → Slack**. No topo da tela, o guia deixa você escolher o modo (**Bot Token** ou **Incoming Webhook**) e mostra só os passos daquele modo.
2. Preencha os campos:
   * **Bot Token (xoxb-...)** — o token copiado na Parte 1. Fica guardado criptografado e volta mascarado na tela depois de salvo.
   * **Incoming Webhook URL** — opcional, alternativa ao Bot Token. No modo webhook, deixe o Bot Token vazio: se ele estiver preenchido, o bot tem prioridade.
   * **Canal padrão** — opcional (ex.: `#geral` ou `C01234ABCDE`). Usado pelo bot quando a chamada de envio não informa `slack_channel`. Não se aplica ao webhook, que sempre entrega no canal fixo dele.
3. Clique em **Testar Conexão**:
   * Bot Token → valida o token e mostra o workspace conectado (*"Conectado: …"*).
   * Somente webhook → envia uma **mensagem de teste real** ao canal do webhook (o Slack não tem modo de teste para webhooks).
4. Clique em **Salvar Configuração**. Salvar já deixa o canal ativo.

## Parte 3 — Criar comunicação e template

1. Acesse **Comunicações → Nova comunicação** e adicione o canal **Slack**. Veja [Comunicações](https://docs.octasend.com.br/plataforma/comunicacoes.md).
2. No template Slack, preencha:
   * **Mensagem (texto)** — obrigatória. Suporta [mrkdwn](https://api.slack.com/reference/surfaces/formatting) (`*negrito*`, `_itálico_`, `código`) e variáveis `{{nome}}`. Serve como mensagem principal, ou como texto alternativo quando o Block Kit está preenchido.
   * **Block Kit (opcional)** — JSON do array de blocks para mensagens ricas (botões, seções, imagens). Monte no [Block Kit Builder](https://app.slack.com/block-kit-builder) e cole aqui **só o array que está em `"blocks"`** (começa com `[`), não o objeto inteiro que o Builder mostra. Variáveis `{{var}}` funcionam em qualquer campo de texto dos blocks, sempre dentro de aspas.
   * **Aparência do bot (opcional)** — **Nome do bot** e **Emoji do ícone** ou **URL do ícone** (um dos dois, não ambos). Esses campos só têm efeito se o app tiver o scope `chat:write.customize`.

O Block Kit é conferido quando você clica em **Salvar rascunho** ou **Publicar**. Se houver problema, o template não é salvo e o editor mostra o motivo:

| Problema | Mensagem |
| - | - |
| JSON inválido (vírgula ou aspas faltando, variável fora de aspas) | *"O JSON do Block Kit é inválido (…). Confira vírgulas e aspas; variáveis como `{{nome}}` precisam ficar entre aspas."* |
| Objeto inteiro do Block Kit Builder (`{"blocks": [...]}`) | *"Cole só o array que está em "blocks" (começa com \[), não o objeto inteiro do Block Kit Builder."* |
| Outro valor que não é um array | *"O Block Kit precisa ser um array de blocks, começando com \[."* |
| Array vazio (`[]`) | *"O Block Kit precisa ter ao menos um bloco. Para enviar só o texto, deixe o campo vazio."* |
| Bloco sem o campo `type` | *"O bloco N do Block Kit precisa ser um objeto com o campo "type"."* |

Para enviar só o texto, deixe o campo Block Kit vazio.

Exemplo de Block Kit com variáveis:

```json theme={null}
[
  {
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": "*Olá {{nome}}!* \nSeu pedido *#{{numero}}* foi confirmado."
    }
  },
  {
    "type": "actions",
    "elements": [
      {
        "type": "button",
        "text": { "type": "plain_text", "text": "Ver Pedido" },
        "url": "https://app.exemplo.com/pedidos/{{numero}}",
        "style": "primary"
      }
    ]
  }
]
```

## Parte 4 — Enviar mensagens via API

Todas as chamadas usam o endpoint `send-message` com um access token — veja [Autenticação](https://docs.octasend.com.br/api-reference/autenticacao.md).

### Opção A — DM por e-mail (requer Bot Token)

A plataforma encontra o usuário do Slack pelo e-mail e abre uma DM:

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "seu_comunicado",
    "recipient": { "email": "usuario@empresa.com" },
    "variables": { "nome": "João" },
    "channels": ["slack"]
  }'
```

> [!NOTE]
>
> O e-mail precisa ser o mesmo cadastrado no perfil Slack do usuário no workspace.

### Opção B — DM por Slack User ID (requer Bot Token)

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "seu_comunicado",
    "recipient": { "slack_user_id": "U01234ABCDE" },
    "variables": { "nome": "João" },
    "channels": ["slack"]
  }'
```

### Opção C — Enviar para canal ou grupo

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "alerta_sistema",
    "recipient": { "slack_channel": "#alertas" },
    "variables": { "servico": "API", "status": "down" },
    "channels": ["slack"]
  }'
```

### Opção D — Só webhook

No modo Incoming Webhook, a mensagem sempre vai para o canal fixo do webhook — o `recipient` pode ir vazio:

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "alerta_sistema",
    "recipient": {},
    "variables": { "servico": "API", "status": "down" },
    "channels": ["slack"]
  }'
```

### Destinos de entrega (a mensagem vai para todos que se aplicarem)

* **Canal:** `recipient.slack_channel` — nome (`#canal`) ou ID (`C01234ABCDE`) — ou o **Canal padrão** da configuração, se nenhum for passado.
* **DM:** `recipient.slack_user_id`, ou `recipient.email` (o usuário é encontrado pelo e-mail).
* **Incoming Webhook:** o canal fixo do webhook, quando não há Bot Token ou quando o bot não tem nenhum canal para esta chamada.

> [!TIP]
>
> Exemplo: com Canal padrão configurado e `recipient.email` na chamada, o destinatário recebe a DM **e** o canal recebe uma cópia — na mesma chamada.

* Se **pelo menos um** destino receber a mensagem, o envio conta como enviado. Se todos falharem, o log registra os motivos de cada destino.
* Sem nenhum destino possível (nem `slack_user_id`, `slack_channel` ou `email` na chamada, nem Canal padrão, nem webhook), o Slack é pulado nessa chamada, sem registro no log.

### Em campanhas

Nas [campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) de Slack, cada contato recebe uma única entrega, e os destinos múltiplos acima não se aplicam:

* **Com Bot Token** — a mensagem vai só por DM ao usuário do Slack que tem o mesmo e-mail do contato. O Canal padrão e o Incoming Webhook ficam de fora, mesmo que estejam configurados. Um contato sem e-mail falha, com o motivo *"Contato sem e-mail: com Bot Token, a campanha no Slack vai por mensagem direta ao usuário do Slack com o e-mail do contato"*.
* **Sem Bot Token** — cada contato gera uma publicação no canal do Incoming Webhook.

## Parte 5 — Verificação e erros comuns

### Checklist

* Bot Token salvo e **Testar Conexão** mostra o nome do workspace.
* Scopes configurados: `chat:write`, `users:read`, `users:read.email`, `im:write`.
* Bot convidado aos canais que precisa acessar (`/invite @bot`).
* Template Slack criado com **Mensagem (texto)** preenchida.
* A chamada `send-message` retorna status `sent` para o canal `slack`.
* O envio aparece em [Logs de Mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md) com o canal Slack resolvido.

### Erros comuns

| Erro | Causa | Solução |
| - | - | - |
| `Bot Token inválido` / `invalid_auth` | Token errado ou de outro workspace | Copie novamente o token `xoxb-` em OAuth & Permissions |
| `Bot Token revogado` / `token_revoked` | App reinstalado ou token revogado | Reinstale o app e salve o novo token |
| `Bot não está no canal …` / `not_in_channel` | Bot não foi convidado ao canal | `/invite @NomeDoBot` no canal de destino |
| `Canal … não encontrado` / `channel_not_found` | Nome ou ID do canal errado, ou canal privado sem o bot | Confira o nome; para privados, convide o bot antes |
| `Nenhum usuário Slack encontrado com o email …` | E-mail não corresponde a nenhum perfil do workspace | Use `slack_user_id`, ou confirme o e-mail no perfil Slack |
| `missing_scope` | Scope faltando no app | Adicione o scope em Bot Token Scopes e **reinstale o app** |
| `URL do Incoming Webhook inválida ou expirada` / `invalid_payload` | Webhook URL errada | Copie de novo a Webhook URL no painel do Slack App |
| `Webhook removido do Slack App` / `no_service` | Webhook apagado no painel do Slack | Crie um novo webhook e atualize a configuração |
| `channel_is_archived` | O canal do webhook foi arquivado | Crie um novo webhook apontando para um canal ativo |
| Mensagem chega com `{{variavel}}` literal | Variável não enviada no payload | Confira o objeto `variables` da chamada |

### Limites

* No Slack, `chat.postMessage` aceita cerca de 1 mensagem por segundo por canal. O disparo de [campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) espaça as mensagens de Slack em cerca de 5 por segundo.
* Block Kit: no máximo 50 blocks por mensagem (limite do Slack).
* Encontrar o usuário pelo e-mail exige o scope `users:read.email` e que o usuário seja do mesmo workspace do app.


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