Pular para conteúdo

SLACK_UPLOAD_FILE - Upload de Arquivo

O que é esta Tool?

A SLACK_UPLOAD_FILE é a tool responsável por fazer upload de arquivos para canais ou DMs do Slack usando a API oficial files.upload.

Por que esta Tool existe?

Upload de arquivos no Slack requer tratamento especial de multipart/form-data. A SLACK_UPLOAD_FILE existe para:

  1. Compartilhar documentos: PDF, DOCX, XLSX automaticamente
  2. Enviar relatórios: Gerar e enviar CSVs, planilhas, logs
  3. Anexar evidências: Screenshots, imagens, arquivos zip
  4. Backup automatizado: Enviar backups diários para canal

Como funciona internamente?

Quando a SLACK_UPLOAD_FILE é executada, o sistema:

  1. Prepara o arquivo (base64, buffer ou URL)
  2. Valida tamanho (limite: varia por tipo de workspace)
  3. Faz upload usando endpoint files.upload ou files.uploadV2
  4. Compartilha no canal ou DM especificado
  5. Se erro: Retorna erro (arquivo muito grande, formato inválido)
  6. Se sucesso: Retorna file ID e URL pública/privada

Código interno (productivity-executors.service.ts - implementação futura):

async executeSlackUploadFile(data: any, variables: Record<string, any>): Promise<any> {
  const { botToken, channel, file, filename, title, initialComment } = data;

  const FormData = require('form-data');
  const form = new FormData();

  form.append('channels', channel);
  form.append('file', file, filename);
  if (title) form.append('title', title);
  if (initialComment) form.append('initial_comment', initialComment);

  const response = await axios.post(
    'https://slack.com/api/files.upload',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'Authorization': `Bearer ${botToken}`,
      }
    }
  );

  if (!response.data.ok) {
    throw new Error(`Slack file upload error: ${response.data.error}`);
  }

  return {
    success: true,
    fileId: response.data.file.id,
    url: response.data.file.url_private,
    permalink: response.data.file.permalink,
    filename: response.data.file.name,
  };
}

Quando você DEVE usar esta Tool?

Use SLACK_UPLOAD_FILE sempre que precisar de enviar arquivos para o Slack:

Casos de uso

  1. Reports automatizados: Enviar CSV de vendas diárias
  2. Logs de sistema: Upload de arquivos de log para investigação
  3. Backups: Enviar dumps de banco de dados
  4. Evidências: Screenshots de erros, comprovantes
  5. Documentação: Compartilhar PDFs, manuais gerados
  6. Planilhas: Excel com dados processados

Quando NÃO usar SLACK_UPLOAD_FILE

  • Mensagens de texto: Use SLACK_SEND_MESSAGE
  • Links externos: Use SLACK_SEND_MESSAGE com URL
  • Arquivos muito grandes: Use serviços de storage (S3, Drive) + link

Parâmetros Detalhados

botToken (string, obrigatório)

O que é: Token de autenticação do Slack Bot.

Permissões necessárias:

  • files:write - Fazer upload de arquivos
  • files:read - Ler informações de arquivos

Flow completo para testar:

{
  "name": "Teste Upload Arquivo Slack",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "slack_1",
      "type": "slack_upload_file",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Upload CSV",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C01234567",
          "file": "data:text/csv;base64,bm9tZSxpZGFkZQpKb8OjbywzMA==",
          "filename": "dados.csv",
          "title": "Relatório de Vendas"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "slack_1" },
    { "source": "slack_1", "target": "end_1" }
  ]
}

channel (string, obrigatório)

O que é: ID do canal ou DM onde o arquivo será compartilhado.

Formatos aceitos:

  • Channel ID: C01234567 (canal público/privado)
  • DM ID: D01234567 (mensagem direta)
  • User ID: U01234567 (abre DM e envia)

Múltiplos canais:

{
  "channel": "C01234567,C98765432,D11111111"
}

file (string/buffer, obrigatório)

O que é: Conteúdo do arquivo a ser enviado.

Formatos aceitos:

1. Base64 Data URL:

data:text/csv;base64,bmFtZSxhZ2UKSm9obiwzMA==

2. Buffer (Node.js):

Buffer.from("Hello World", 'utf-8')

3. File path (local):

/tmp/report.pdf

4. URL externa:

https://exemplo.com/arquivo.pdf

filename (string, obrigatório)

O que é: Nome do arquivo que aparecerá no Slack.

Exemplos:

relatorio-vendas-2025-01.pdf
logs-server-01.txt
backup-database.sql.gz
screenshot-error.png

title (string, opcional)

O que é: Título do arquivo exibido no Slack.

Padrão: Nome do arquivo (filename)

Exemplo:

{
  "filename": "report.pdf",
  "title": "Relatório Mensal de Vendas - Janeiro 2025"
}

initialComment (string, opcional)

O que é: Mensagem que acompanha o arquivo.

Padrão: undefined (sem comentário)

Suporta Markdown:

*Relatório pronto!*
@channel Por favor, revisar até amanhã

Flow completo para testar:

{
  "name": "Upload com Comentário",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "slack_1",
      "type": "slack_upload_file",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Upload Report",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "reports",
          "file": "data:text/csv;base64,..base64..",
          "filename": "vendas-jan.csv",
          "title": "Vendas Janeiro 2025",
          "initialComment": "📊 *Relatório pronto!*\n\n@channel Por favor, revisar os números."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "slack_1" },
    { "source": "slack_1", "target": "end_1" }
  ]
}

Parâmetros

Campo Tipo Obrigatório Descrição
botToken string Sim Token do Bot (xoxb-...) com scope files:write
channel string Sim ID do canal/DM (C01234567, D01234567, U01234567)
file string/buffer Sim Conteúdo do arquivo (base64, buffer, path, URL)
filename string Sim Nome do arquivo (report.pdf, data.csv)
title string Não Título exibido no Slack (padrão: filename)
initialComment string Não Mensagem que acompanha o arquivo

Exemplo 1: Enviar CSV de Vendas

Objetivo: Gerar e enviar relatório CSV automaticamente

JSON para Importar

{
  "name": "Upload CSV Vendas",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Gerar CSV",
        "parameters": {
          "variableName": "csvData",
          "value": "nome,valor,data\nJoão Silva,1500,2025-01-15\nMaria Santos,2500,2025-01-15\nPedro Costa,1800,2025-01-15"
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_upload_file",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Upload CSV",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "vendas",
          "file": "data:text/csv;base64,{{csvData | base64}}",
          "filename": "vendas-diarias-2025-01-15.csv",
          "title": "Relatório de Vendas - 15/01/2025",
          "initialComment": "📊 *Relatório diário pronto!*\n\nTotal de vendas: 3\nValor total: R$ 5.800\n\n@channel"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "slack_1" },
    { "source": "slack_1", "target": "end_1" }
  ]
}

Saída esperada no Slack:

📊 Relatório diário pronto!

Total de vendas: 3
Valor total: R$ 5.800

@channel

[📄 vendas-diarias-2025-01-15.csv]
Relatório de Vendas - 15/01/2025

Exemplo 2: Backup Automático

Objetivo: Enviar backup de banco de dados diariamente

JSON para Importar

{
  "name": "Backup Diário Slack",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "slack_1",
      "type": "slack_upload_file",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Upload Backup",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "devops-backups",
          "file": "/backups/database-2025-01-15.sql.gz",
          "filename": "backup-prod-2025-01-15.sql.gz",
          "title": "Backup Produção - 15/01/2025",
          "initialComment": "✅ Backup automático concluído\n\n📅 Data: 15/01/2025\n⏰ Hora: 03:00 AM\n💾 Tamanho: 2.3 GB\n🗄️ Banco: PostgreSQL Prod"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "slack_1" },
    { "source": "slack_1", "target": "end_1" }
  ]
}

Exemplo 3: Log de Erros

Objetivo: Enviar arquivo de log quando ocorrer erro

JSON para Importar

{
  "name": "Enviar Log Erro",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Erro Detectado",
        "parameters": {
          "variableName": "error",
          "value": {
            "timestamp": "2025-01-15T10:30:00Z",
            "service": "API Gateway",
            "message": "Connection timeout",
            "stack": "Error at line 456..."
          }
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_upload_file",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Upload Log",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "alerts",
          "file": "/var/logs/api-errors.log",
          "filename": "api-errors-2025-01-15.log",
          "title": "Log de Erros - API Gateway",
          "initialComment": "🚨 *Erro detectado no sistema*\n\n🖥️ Serviço: {{error.service}}\n⏰ Timestamp: {{error.timestamp}}\n❌ Erro: {{error.message}}\n\n@devops Por favor, investigar!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "slack_1" },
    { "source": "slack_1", "target": "end_1" }
  ]
}

Resposta da Tool

{
  "success": true,
  "fileId": "F01234567ABC",
  "url": "https://files.slack.com/files-pri/T012-F012/report.pdf",
  "permalink": "https://myworkspace.slack.com/files/U012/F012/report.pdf",
  "filename": "report.pdf"
}

Limites de Upload

Plano Slack Tamanho Máximo por Arquivo
Free 5 MB
Pro 20 GB
Business+ 20 GB
Enterprise Grid 20 GB

Nota: Para arquivos grandes, considere usar storage externo (S3, Drive) e enviar link.

Tipos de Arquivo Suportados

✅ Documentos:

  • PDF, DOC, DOCX, TXT, RTF
  • XLS, XLSX, CSV
  • PPT, PPTX

✅ Imagens:

  • PNG, JPG, JPEG, GIF, BMP
  • SVG, WEBP

✅ Código:

  • JS, TS, PY, JAVA, GO, PHP
  • JSON, XML, YAML, HTML, CSS

✅ Arquivos:

  • ZIP, TAR, GZ, 7Z
  • SQL, LOG, MD

✅ Áudio/Vídeo:

  • MP3, WAV, MP4, AVI, MOV

Boas Práticas

✅ SIM:

  • Usar nomes de arquivo descritivos com data
  • Incluir title diferente de filename quando relevante
  • Adicionar initialComment explicando o conteúdo
  • Comprimir arquivos grandes (.zip, .gz)
  • Validar tamanho antes de upload
  • Usar canais específicos para tipos de arquivo (backups, reports, logs)

❌ NÃO:

  • Não faça upload de arquivos com dados sensíveis sem criptografia
  • Não envie arquivos enormes (use storage externo)
  • Não faça upload de vírus ou malware (óbvio, mas...)
  • Não abuse fazendo uploads em massa

Dicas

💡 Base64: Para gerar base64 de string: Buffer.from("texto").toString('base64')

💡 CSV Dinâmico: Gere CSV em tempo real e faça upload imediato

💡 Compressão: Use .gz para arquivos de log grandes

💡 Múltiplos canais: Envie para vários canais separando IDs por vírgula

💡 Threads: Use thread_ts para anexar arquivo em thread existente

💡 Private URLs: URLs retornadas são privadas - apenas membros do workspace podem acessar

Erros Comuns

file_too_large

Causa: Arquivo excede limite do plano Solução: Comprima ou use storage externo + link

invalid_file_type

Causa: Tipo de arquivo não suportado Solução: Converta para formato aceito ou envie como .txt

missing_scope

Causa: Bot não tem scope files:write Solução: Adicione scope e reinstale app

channel_not_found

Causa: Channel ID inválido Solução: Verifique o ID do canal

Files Upload V2 API

Slack tem nova API files.uploadV2 para arquivos grandes (>1 MB):

Vantagens:

  • Suporta arquivos maiores
  • Upload em chunks
  • Melhor performance

Código exemplo:

// Upload em 2 etapas
// 1. Obter upload URL
const getUploadUrl = await slack.files.getUploadURLExternal({
  filename: 'large-file.zip',
  length: fileSize
});

// 2. Upload via HTTP
await axios.put(getUploadUrl.upload_url, fileBuffer);

// 3. Completar upload
await slack.files.completeUploadExternal({
  files: [{ id: getUploadUrl.file_id }],
  channel_id: 'C01234567'
});

Próxima Tool

→ SLACK_SEND_MESSAGE - Enviar mensagem → SLACK_CREATE_CHANNEL - Criar canal → SLACK_REACT_MESSAGE - Adicionar reação