Slack Bot

Multica는 사용자가 직접 만든 Slack app을 사용합니다. 연결하면 팀 멤버가 Bot과 DM을 나누고 채널에서 @멘션하거나 /issue로 이슈를 만들 수 있습니다.

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]"
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - 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가 작동하지 않을 수 있습니다.

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의 최근 컨텍스트를 읽습니다.

/issue로 이슈 만들기

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

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

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

연결 관리

설정 → 연동에서 연결된 모든 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가 없음: manifest에 slash command와 commands scope가 포함되어 있는지 확인하고 app을 다시 설치합니다.
• Bot이 실행되지 않음: 에이전트가 보관 처리되었는지, 사용하는 런타임이 온라인인지 확인합니다.

다음 단계

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