SLACK_INVITE_USER - Convidar Usuário para Canal

O que é esta Tool?

A SLACK_INVITE_USER é a tool responsável por adicionar usuários a canais públicos ou privados do Slack programaticamente.

Por que esta Tool existe?

Adicionar usuários manualmente é lento em automações. A SLACK_INVITE_USER existe para:

Onboarding automatizado: Adicionar novos membros aos canais corretos
Gestão dinâmica de projetos: Adicionar membros quando atribuídos a projeto
Controle de acesso: Adicionar usuários a canais privados baseado em regras
Automação de workflows: Adicionar stakeholders automaticamente

Como funciona internamente?

Quando a SLACK_INVITE_USER é executada, o sistema:

Valida user ID e channel ID
Verifica se usuário já está no canal
Convida usuário usando endpoint conversations.invite
Se erro: Retorna erro (usuário já no canal, sem permissão, canal arquivado)
Se sucesso: Confirma que usuário foi adicionado

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

async executeSlackInviteUser(data: any, variables: Record<string, any>): Promise<any> {
  const { botToken, channel, userId, users } = data;

  // Suporta múltiplos usuários
  const userIds = users || [userId];

  const inviteUrl = 'https://slack.com/api/conversations.invite';
  const response = await axios.post(inviteUrl,
    {
      channel: channel,
      users: userIds.join(','),
    },
    {
      headers: {
        'Authorization': `Bearer ${botToken}`,
        'Content-Type': 'application/json',
      }
    }
  );

  if (!response.data.ok) {
    // Ignorar erro se usuário já está no canal
    if (response.data.error === 'already_in_channel') {
      return {
        success: true,
        message: 'User already in channel',
        alreadyMember: true,
      };
    }
    throw new Error(`Failed to invite user: ${response.data.error}`);
  }

  return {
    success: true,
    channel: channel,
    users: userIds,
    message: 'User(s) invited successfully',
  };
}

Quando você DEVE usar esta Tool?

Use SLACK_INVITE_USER sempre que precisar de adicionar usuários automaticamente:

Casos de uso

Onboarding: Adicionar novo funcionário aos canais da empresa
Atribuição de projeto: Adicionar membro quando atribuído a projeto
Criação de canal: Adicionar membros relevantes após criar canal
Mudança de departamento: Adicionar a canais do novo departamento
Acesso a cliente: Adicionar account manager a canal privado do cliente
Incident response: Adicionar time de on-call a canal de incidente

Quando NÃO usar SLACK_INVITE_USER

Canal público e usuário pode entrar: Deixe o usuário entrar voluntariamente
Spam: Não adicione usuários a canais irrelevantes
Guest users: Guests têm restrições especiais

Parâmetros Detalhados

botToken (string, obrigatório)

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

Permissões necessárias: - channels:manage - Adicionar usuários a canais públicos - groups:write - Adicionar usuários a canais privados

Flow completo para testar:

{
  "name": "Teste Convidar Usuário",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Convidar Usuário",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C01234567",
          "userId": "U98765432"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Usuário adicionado ao canal!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "slack_1" },
    { "source": "slack_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

channel (string, obrigatório)

O que é: ID do canal onde o usuário será adicionado.

Formatos aceitos: - Channel ID público: C01234567 - Channel ID privado: G01234567

Como obter Channel ID: 1. Clique com botão direito no canal 2. View channel details 3. Copie o Channel ID no final da página

Flow completo para testar:

{
  "name": "Adicionar a Canal Específico",
  "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": "Definir Canal",
        "parameters": {
          "variableName": "canalProjeto",
          "value": "C01234567"
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar Membro",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "{{canalProjeto}}",
          "userId": "U98765432"
        }
      }
    },
    {
      "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" }
  ]
}

userId (string, obrigatório se users não fornecido)

O que é: ID único do usuário Slack a ser adicionado.

Como obter User ID: 1. Clique no perfil do usuário 2. Mais opções (...) 3. Copy member ID

Alternativa: Use API users.lookupByEmail para obter ID por email

Flow completo para testar:

{
  "name": "Convidar por User ID",
  "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": "Novo Membro",
        "parameters": {
          "variableName": "novoMembro",
          "value": {
            "id": "U98765432",
            "nome": "João Silva",
            "email": "joao@empresa.com"
          }
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar ao Canal",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C01234567",
          "userId": "{{novoMembro.id}}"
        }
      }
    },
    {
      "id": "slack_2",
      "type": "slack_send_dm",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Notificar Usuário",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "userId": "{{novoMembro.id}}",
          "text": "👋 Olá {{novoMembro.nome}}! Você foi adicionado ao canal #projeto-x"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "slack_1" },
    { "source": "slack_1", "target": "slack_2" },
    { "source": "slack_2", "target": "end_1" }
  ]
}

users (array, opcional)

O que é: Array de User IDs para adicionar múltiplos usuários de uma vez.

Padrão: undefined (usa apenas userId)

Formato:

{
  "users": ["U01234567", "U98765432", "U11111111"]
}

Limite: Até 1000 usuários por chamada (prática recomendada: batches de 50)

Flow completo para testar:

{
  "name": "Adicionar Múltiplos Usuários",
  "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": "Lista de Membros",
        "parameters": {
          "variableName": "membros",
          "value": ["U01234567", "U98765432", "U11111111"]
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar Todos",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C01234567",
          "users": "{{membros}}"
        }
      }
    },
    {
      "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" }
  ]
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
botToken	string	Sim	Token do Bot (channels:manage, groups:write)
channel	string	Sim	ID do canal (C01234567 ou G01234567)
userId	string	Condicional	User ID único (U01234567)
users	array	Condicional	Array de User IDs para batch

Nota: Forneça userId OU users, não ambos.

Exemplo 1: Onboarding Automatizado

Objetivo: Adicionar novo funcionário a todos os canais relevantes

JSON para Importar

{
  "name": "Onboarding - Adicionar a Canais",
  "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": "Novo Funcionário",
        "parameters": {
          "variableName": "newEmployee",
          "value": {
            "id": "U01234567",
            "nome": "Maria Santos",
            "departamento": "Engenharia",
            "cargo": "Desenvolvedora"
          }
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar a #geral",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C_GERAL",
          "userId": "{{newEmployee.id}}"
        }
      }
    },
    {
      "id": "slack_2",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 200 },
      "data": {
        "label": "Adicionar a #engenharia",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C_ENGENHARIA",
          "userId": "{{newEmployee.id}}"
        }
      }
    },
    {
      "id": "slack_3",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 300 },
      "data": {
        "label": "Adicionar a #random",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "C_RANDOM",
          "userId": "{{newEmployee.id}}"
        }
      }
    },
    {
      "id": "slack_4",
      "type": "slack_send_dm",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Notificar",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "userId": "{{newEmployee.id}}",
          "text": "🎉 Bem-vinda {{newEmployee.nome}}!\n\nVocê foi adicionada aos seguintes canais:\n• #geral - Comunicação geral\n• #engenharia - Time de engenharia\n• #random - Conversas descontraídas\n\nExplore e se apresente! 👋"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "slack_1" },
    { "source": "variable_1", "target": "slack_2" },
    { "source": "variable_1", "target": "slack_3" },
    { "source": "slack_1", "target": "slack_4" },
    { "source": "slack_2", "target": "slack_4" },
    { "source": "slack_3", "target": "slack_4" },
    { "source": "slack_4", "target": "end_1" }
  ]
}

Exemplo 2: Adicionar Time ao Projeto

Objetivo: Quando projeto inicia, adicionar todos os membros do time

JSON para Importar

{
  "name": "Adicionar Time a Projeto",
  "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": "Dados Projeto",
        "parameters": {
          "variableName": "projeto",
          "value": {
            "canal": "C_PROJETO_X",
            "time": ["U01111111", "U02222222", "U03333333", "U04444444"],
            "nome": "Projeto X"
          }
        }
      }
    },
    {
      "id": "slack_1",
      "type": "slack_invite_user",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Adicionar Time",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "{{projeto.canal}}",
          "users": "{{projeto.time}}"
        }
      }
    },
    {
      "id": "slack_2",
      "type": "slack_send_message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Anunciar",
        "parameters": {
          "botToken": "xoxb-seu-token-aqui",
          "channel": "{{projeto.canal}}",
          "text": "🎉 Time completo adicionado ao {{projeto.nome}}!\n\nVamos começar! 🚀"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "slack_1" },
    { "source": "slack_1", "target": "slack_2" },
    { "source": "slack_2", "target": "end_1" }
  ]
}

Resposta da Tool

{
  "success": true,
  "channel": "C01234567",
  "users": ["U01234567", "U98765432"],
  "message": "User(s) invited successfully"
}

Boas Práticas

✅ SIM:

Notificar usuários após adicioná-los (via DM ou mensagem no canal)
Explicar por que foram adicionados
Fornecer contexto do canal
Usar batch (users array) para múltiplos usuários
Verificar se usuário já está no canal (ignorar erro already_in_channel)

❌ NÃO:

Não adicione usuários a canais irrelevantes
Não adicione sem contexto ou explicação
Não abuse adicionando a muitos canais de uma vez
Não adicione a canais privados sem necessidade clara

Dicas

💡 Batch operations: Use array users para adicionar múltiplos de uma vez

💡 Idempotência: Se usuário já está no canal, API retorna erro already_in_channel - trate como sucesso

💡 Notificação: Sempre envie DM explicando o contexto

💡 Permissões: Para canais privados, bot precisa scope groups:write

💡 Limite: API aceita até 1000 usuários, mas recomenda-se batches de 50 para melhor performance

Erros Comuns

`already_in_channel`

Causa: Usuário já é membro do canal Solução: Ignore este erro (usuário já tem acesso)

`channel_not_found`

Causa: Channel ID inválido ou canal não existe Solução: Verifique o Channel ID

`user_not_found`

Causa: User ID inválido Solução: Verifique o User ID usando API users.list

`cant_invite_self`

Causa: Tentando adicionar o próprio bot Solução: Bots são adicionados automaticamente quando instalados

`is_archived`

Causa: Canal está arquivado Solução: Desarquive o canal primeiro (unarchive)

`missing_scope`

Causa: Bot não tem permissão Solução: Adicione scope channels:manage (público) ou groups:write (privado)

Workflow Típico

1. Criar canal
2. Definir descrição/tópico
3. Adicionar membros (slack_invite_user)
4. Enviar mensagem de boas-vindas
5. Notificar membros via DM

Próxima Tool

→ SLACK_CREATE_CHANNEL - Criar canal → SLACK_ARCHIVE_CHANNEL - Arquivar canal → SLACK_SET_TOPIC - Definir tópico