Slack

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 seguem outra regra, com uma entrega por contato — veja Em campanhas.

Parte 1 — Criar o Slack App

Acesse api.slack.com/apps e clique em Create New App → From scratch.
Dê um nome ao app (ex.: OctaSend) e selecione o workspace de destino.
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
Ainda em OAuth & Permissions, clique em Install to Workspace e autorize.
Copie o Bot User OAuth Token — começa com xoxb-.

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:

Abra Incoming Webhooks e ative a opção.
Clique em Add New Webhook to Workspace, selecione o canal de destino e autorize.
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

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.
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.
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).
Clique em Salvar Configuração. Salvar já deixa o canal ativo.

Parte 3 — Criar comunicação e template

Acesse Comunicações → Nova comunicação e adicione o canal Slack. Veja Comunicações.
No template Slack, preencha:
- Mensagem (texto) — obrigatória. Suporta mrkdwn (*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 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:

[
  {
    "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.

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:

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"]
  }'

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)

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

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:

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.

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 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 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 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.

Primeiros Passos

Mensageria

Guias de Canais

Atendimento e IA

Site e engajamento

E-commerce

Integrações

Conta e ferramentas

API Reference

Como o canal funciona

Parte 1 — Criar o Slack App

(Opcional) Incoming Webhook

Parte 2 — Configurar o canal na plataforma

Parte 3 — Criar comunicação e template

Parte 4 — Enviar mensagens via API

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

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

Opção C — Enviar para canal ou grupo

Opção D — Só webhook

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

Em campanhas

Parte 5 — Verificação e erros comuns

Checklist

Erros comuns

Limites

​Como o canal funciona

​Parte 1 — Criar o Slack App

​(Opcional) Incoming Webhook

​Parte 2 — Configurar o canal na plataforma

​Parte 3 — Criar comunicação e template

​Parte 4 — Enviar mensagens via API

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

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

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

​Opção D — Só webhook

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

​Em campanhas

​Parte 5 — Verificação e erros comuns

​Checklist

​Erros comuns

​Limites

Como o canal funciona

Parte 1 — Criar o Slack App

(Opcional) Incoming Webhook

Parte 2 — Configurar o canal na plataforma

Parte 3 — Criar comunicação e template

Parte 4 — Enviar mensagens via API

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

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

Opção C — Enviar para canal ou grupo

Opção D — Só webhook

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

Em campanhas

Parte 5 — Verificação e erros comuns

Checklist

Erros comuns

Limites