Slack Bot

Multica는 사용자가 직접 만든 Slack app을 사용합니다. 연결하면 팀 멤버가 Bot과 DM을 나누고, 채널에서 @멘션하고, /issue로 태스크를 만들고, /new으로 새 Multica Chat을 시작하거나 /clear로 현재 Chat의 에이전트 컨텍스트를 초기화할 수 있습니다.

Slack app 하나는 Multica 에이전트 하나에 대응합니다. 여러 에이전트를 연결하려면 에이전트마다 별도의 app을 만드세요.

시작하기 전에

연결은 워크스페이스 owner 또는 admin이 완료해야 하며 마지막에 두 자격 증명을 Multica에 입력합니다.

• xoxb-로 시작하는 Bot User OAuth Token
• xapp-로 시작하는 App-level Token

1. manifest에서 Slack app 만들기

Slack API Apps를 열고 Create New App → From a manifest를 클릭한 뒤 Slack workspace를 선택하고 YAML에 다음 내용을 붙여 넣습니다.

display_information:
  name: Multica
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Multica
    always_online: true
  slash_commands:
    - command: /issue
      description: Create a Multica issue
      usage_hint: "[description]"
    - command: /new
      description: Start a new Multica chat
      usage_hint: "[message]"
    - command: /clear
      description: Clear the current Multica chat context
      usage_hint: "[message]"
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - files:read
      - groups:history
      - im:history
      - mpim:history
      - chat:write
      - reactions:write
      - users:read
      - commands
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
      - message.channels
      - message.groups
      - message.mpim
  interactivity:
    is_enabled: false
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

만들기 전에 두 Multica 값을 에이전트 이름으로 바꿀 수 있습니다. manifest의 권한이나 이벤트를 삭제하지 마세요. 삭제하면 DM, 채널 멘션, 답글, /issue, /new, /clear가 작동하지 않을 수 있습니다.

Bot은 Socket Mode로 Slack에 능동적으로 연결하므로 공개 Request URL이나 OAuth Redirect URL을 설정할 필요가 없습니다.

2. 두 token 받기

Bot token

1. Slack app에서 Install App을 엽니다.
2. Install to Workspace를 클릭하고 권한을 승인합니다.
3. xoxb-로 시작하는 Bot User OAuth Token을 복사합니다.

App-level token

1. Basic Information → App-Level Tokens를 엽니다.
2. Generate Token and Scopes를 클릭합니다.
3. connections:write scope를 추가합니다.
4. xapp-로 시작하는 token을 생성하고 복사합니다.

3. 에이전트에 연결

1. Multica에서 에이전트를 열고 Slack에 연결할 에이전트를 선택합니다.
2. 연동으로 이동해 Slack 연결을 클릭합니다.
3. Bot token과 App-level token을 입력합니다.
4. 연결을 클릭합니다.

Multica가 두 token이 같은 app에서 발급되었는지 확인합니다. 연결에 성공하면 페이지에 Slack에 연결됨이 표시됩니다.

처음 사용

멤버가 처음으로 Bot과 DM을 나누거나 @멘션하면 계정 연결 링크를 받습니다. 해당 워크스페이스의 Multica 계정으로 로그인한 뒤 Slack으로 돌아가 메시지를 다시 보내세요.

링크는 한 번만 사용할 수 있고 15분 뒤 만료됩니다. 만료되면 Bot에 메시지를 하나 더 보내 새 링크를 받으면 됩니다. 같은 Multica 워크스페이스의 여러 Bot이 같은 Slack workspace에서 만들어졌다면 기존 연결을 보통 재사용할 수 있습니다.

현재 Multica 워크스페이스의 멤버만 Bot을 사용할 수 있습니다.

Slack에서 작업 요청

DM

Slack 사이드바의 Apps에서 Bot을 열고 바로 메시지를 보냅니다. @멘션은 필요 없습니다.

채널과 그룹 채팅

먼저 /invite @your-bot을 실행해 Bot을 채널에 추가하고 @your-bot 요청 내용을 보냅니다. 각 thread는 독립된 대화가 됩니다. 후속 질문은 원래 thread에서 Bot을 계속 @멘션하세요.

Bot은 자신을 명시적으로 @멘션한 채널 메시지에만 응답합니다. 실행할 때 권한 범위 안에서 해당 thread의 최근 컨텍스트를 읽습니다.

파일 보내기

DM이나 Bot을 @멘션한 채널 메시지에 파일을 그대로 첨부하세요. 파일은 같은 작업의 첨부 파일로 전달되므로 에이전트가 요청 내용과 함께 읽을 수 있습니다.

이 기능에는 files:read scope가 필요합니다. 첨부 파일 지원 이전에 설치한 app이라면 1단계의 안내를 참고하세요. 파일 하나는 20 MiB 이하여야 하고 메시지 하나에 최대 10개까지 담깁니다. 용량을 초과했거나 아직 업로드 중이거나 Slack 외부에 있는 파일(예: Google Drive, Dropbox 링크)은 건너뛰며, 메시지 본문은 그대로 에이전트에 전달됩니다.

/issue로 태스크 만들기

채널이나 DM에서 다음을 입력합니다.

/issue Safari에서 로그인에 성공해도 로그인 페이지에 계속 머뭅니다.

이 명령에는 Bot @멘션이 필요 없습니다. Multica가 설명을 현재 Bot에 연결된 에이전트로 보내고 에이전트가 제목과 본문을 정리해 태스크를 만듭니다. Slack에는 먼저 나에게만 보이는 접수 메시지가 표시되며 생성이 끝나면 Multica 인박스에 알림이 도착합니다.

/new으로 새 Chat 시작하기

Bot과의 DM에서 /new을 보내면 비어 있는 새 Chat이 즉시 생성되어 Multica에 표시됩니다. /new <메시지>를 보내면 해당 메시지가 새 Chat의 첫 번째 대화가 됩니다. 인자 없는 /new은 첫 번째 유효한 사용자 메시지가 도착할 때까지 “새 채팅”으로 표시되고, 이후에는 기존의 첫 메시지 제목 처리 방식을 따릅니다.

이전 Chat은 Multica의 웹, 데스크톱, 모바일에 남아 있으며 계속 메시지를 보낼 수 있습니다. 이 Slack 대화의 후속 메시지만 새 Chat으로 라우팅됩니다.

채널이나 thread에서는 Slack의 네이티브 slash command payload로 대상 thread를 식별할 수 없습니다. 대상 thread에서 @Multica /new [메시지]를 보내세요.

/clear로 현재 Chat 컨텍스트 지우기

Bot과의 DM에서 /clear를 보내면 현재 Multica Chat은 유지되고 에이전트에게 보이는 컨텍스트만 초기화됩니다. 전체 Chat 기록은 Multica에 그대로 저장됩니다. /clear <메시지>는 해당 메시지를 새 컨텍스트의 첫 번째 대화로 사용하고, 인자 없는 /clear는 다음 실제 메시지에 경계를 적용합니다.

채널이나 thread에서는 대상 thread에서 @Multica /clear [메시지]를 보내세요.

연결 관리

설정 → 연동에서 연결된 모든 Slack Bot을 확인할 수 있습니다. 워크스페이스 owner와 admin이 연결을 해제할 수 있습니다.

연결을 해제하면 Socket Mode 연결이 중지되고 Bot이 새 메시지를 받지 않습니다. 기존 대화와 감사 기록은 함께 삭제되지 않습니다.

자체 호스팅 설정

Multica Cloud에는 추가 설정이 필요 없습니다. 자체 호스팅 환경에서는 Slack token 암호화에 사용할 키를 먼저 설정해야 합니다.

MULTICA_SLACK_SECRET_KEY=<base64로 인코딩한 32바이트 키>

다음과 같이 생성할 수 있습니다.

openssl rand -base64 32

API 서비스를 다시 시작한 뒤 Slack app을 연결하세요. 이 키는 장기간 보관해야 합니다. 키를 바꾸거나 잃어버리면 기존 token을 복호화할 수 없으므로 다시 연결해야 합니다.

계정 연결 링크는 MULTICA_APP_URL을 사용하고, 설정되지 않으면 FRONTEND_ORIGIN을 사용합니다. 멤버가 접근할 수 있는 Multica 주소를 지정해야 합니다.

자주 묻는 문제

• 연결할 때 token이 유효하지 않다고 표시됨: 접두사를 확인하고 두 token이 같은 app에서 발급되었는지 확인합니다.
• app을 확인할 수 없음: manifest에 users:read가 포함되어 있는지 확인하고 권한을 업데이트한 뒤 app을 다시 설치합니다.
• DM 메뉴가 없음: app_home.messages_tab_enabled가 true인지 확인합니다.
• 채널에서 답변이 없음: Bot이 채널에 초대되었고 메시지에서 @멘션했는지 확인합니다.
• /issue, /new 또는 /clear가 없음: manifest에 세 slash command와 commands scope가 포함되어 있는지 확인하고 app을 다시 설치합니다. Slack에서 /new 또는 /clear가 이미 사용 중이라고 표시되면 @Multica 메시지 형식을 사용하거나 workspace 수준의 명령 충돌을 먼저 해결하세요.
• 파일이 에이전트에 도착하지 않음: manifest에 files:read가 포함되어 있는지, scope를 추가한 뒤 app을 다시 설치했는지 확인하고, 파일이 20 MiB 이하인지도 확인합니다.
• Bot이 실행되지 않음: 에이전트가 보관 처리되었는지, 사용하는 런타임이 온라인인지 확인합니다.

다음 단계

• 채팅 연동 — 플랫폼 비교, 대화 격리, 계정 연결 방식을 알아봅니다.
• 에이전트와 대화 — Bot 뒤의 대화 및 실행 모델을 알아봅니다.
• 태스크 — /issue가 만드는 작업 단위를 알아봅니다.