11.4. 멀티 채널 메시징¶

멀티 채널 메시징을 사용하면 에이전트가 외부 채팅 플랫폼(Telegram, Slack, Discord, WhatsApp)에서 오는 메시지에 응답할 수 있습니다. 설정을 마치면 봇으로 들어온 메시지가 알맞은 Squad 그룹으로 라우팅되어 처리되고, 에이전트의 답변은 같은 채널을 통해 되돌아갑니다.

아키텍처¶

flowchart LR
    subgraph Channels["채널"]
        TG[Telegram]
        SL[Slack]
        DC[Discord]
        WA[WhatsApp]
    end

    subgraph Core["Backend.AI GO"]
        CR[채널 레지스트리]
        AL[발신자 허용 목록]
        MR[메시지 라우터]
        SQ[Squad 그룹]
    end

    TG & SL & DC & WA --> CR
    CR --> AL
    AL -- 허용 --> MR
    AL -- 차단 --> X[거부됨]
    MR --> SQ
    SQ --> MR
    MR --> TG & SL & DC & WA

공통 설정 절차¶

채널마다 다음 순서로 진행합니다.

플랫폼의 개발자 포털에서 봇 또는 앱 생성
필요한 토큰/자격증명 복사
Backend.AI GO에서 채널 연결
채널의 채팅을 Squad 그룹에 매핑
(선택) 발신자 허용 목록 설정

Telegram¶

Telegram 봇 생성¶

Telegram을 열고 @BotFather와 채팅을 시작합니다.
/newbot을 전송하고 안내를 따릅니다:
- 표시 이름을 선택합니다 (예: "내 AI 어시스턴트")
- bot으로 끝나는 사용자명을 선택합니다 (예: myai_assistant_bot)
BotFather가 봇 토큰(형식: 1234567890:ABCdef...)을 답장으로 보내 주는데, 이 값을 복사해 둡니다.

Backend.AI GO에서 Telegram 연결¶

설정 > 채널 > Telegram으로 이동합니다.
토큰 필드에 봇 토큰을 붙여넣습니다.
토큰 검증을 클릭해 토큰이 유효한지 확인합니다.
연결을 클릭합니다.
봇이 연결되면 상태 표시등이 녹색으로 바뀝니다.

Telegram 트리거 동작¶

채팅 유형	트리거
다이렉트 메시지(DM)	모든 메시지가 봇을 트리거
그룹 채팅	봇을 @멘션한 메시지가 트리거

JID 형식¶

Telegram 채팅 식별자는 tg:{chat_id} 형식을 사용합니다 (예: tg:123456789).

Slack¶

Slack 앱 생성¶

api.slack.com/apps에서 새 앱 만들기를 클릭합니다.
처음부터를 선택한 뒤 앱 이름을 입력하고 워크스페이스를 선택합니다.
왼쪽 사이드바에서 OAuth 및 권한을 클릭합니다.
봇 토큰 범위 아래에 다음 범위를 추가합니다:
- app_mentions:read
- channels:history
- chat:write
- groups:history
- im:history
- im:read
- im:write
워크스페이스에 설치를 클릭하고 권한을 부여합니다. 봇 사용자 OAuth 토큰(xoxb-...)을 복사합니다.
왼쪽 사이드바에서 소켓 모드를 클릭해 활성화한 다음, connections:write 범위로 앱 수준 토큰을 만들고 앱 토큰(xapp-...)을 복사합니다.
이벤트 구독에서 이벤트를 활성화하고 다음을 구독합니다:
- app_mention
- message.im

Backend.AI GO에서 Slack 연결¶

설정 > 채널 > Slack으로 이동합니다.
봇 토큰(xoxb-...)과 앱 토큰(xapp-...)을 붙여넣습니다.
토큰 검증을 클릭해 두 토큰을 모두 확인합니다.
연결을 클릭합니다.

Slack 트리거 동작¶

이벤트	트리거
`app_mention`	채널에서 봇을 @멘션할 때
`message.im`	봇에게 보내는 모든 다이렉트 메시지

JID 형식¶

Slack 채팅 식별자는 slack:{channel_id} 형식을 사용합니다 (예: slack:C01234567).

Discord¶

Discord 봇 생성¶

Discord 개발자 포털에서 새 애플리케이션을 클릭합니다.
이름을 지정하고 생성을 클릭합니다.
왼쪽 사이드바에서 봇을 클릭합니다.
봇 추가를 클릭하고 확인합니다.
토큰 아래에서 토큰 재설정을 클릭하고 토큰을 복사합니다.
특권 게이트웨이 인텐트 아래에서 다음을 활성화합니다:
- 메시지 내용 인텐트 (메시지 텍스트를 읽는 데 필요)
OAuth2 > URL 생성기에서 범위로 bot을 선택하고, 봇 권한으로 다음을 선택합니다:
- 메시지 읽기/채널 보기
- 메시지 보내기
- 메시지 기록 읽기
생성된 OAuth2 URL을 브라우저에서 열어 봇을 서버에 초대합니다.

Backend.AI GO에서 Discord 연결¶

설정 > 채널 > Discord로 이동합니다.
봇 토큰을 붙여넣습니다.
토큰 검증을 클릭합니다.
연결을 클릭합니다.

Discord 트리거 동작¶

채팅 유형	트리거
길드 텍스트 채널	봇을 @멘션할 때
다이렉트 메시지	모든 메시지가 봇을 트리거

JID 형식¶

Discord 채팅 식별자는 discord:{channel_id} 형식을 사용합니다 (예: discord:123456789012345678).

WhatsApp Business¶

WhatsApp은 WhatsApp Business Cloud API를 사용하며 인증된 Meta 비즈니스 계정이 필요합니다.

사전 요구 사항¶

Meta 개발자 계정
WhatsApp Business 계정
WhatsApp Business API 전용 전화번호

WhatsApp Business API 설정¶

developers.facebook.com에서 비즈니스 유형의 새 앱을 생성합니다.
앱에 WhatsApp 제품을 추가합니다.
WhatsApp 설정 화면에서 다음 값을 적어 둡니다:
- 전화번호 ID (WhatsApp 전화번호의 숫자 ID)
- WhatsApp Business 계정 ID
영구 액세스 토큰을 생성합니다 (테스트 중에는 임시 토큰도 가능):
- Meta Business Suite > 시스템 사용자로 이동합니다
- whatsapp_business_messaging 권한을 가진 시스템 사용자를 만듭니다
- 그 시스템 사용자용 토큰을 생성합니다
웹훅을 설정합니다:
- 웹훅 URL: https://{your-domain}/api/v1/channels/whatsapp/webhook
- 검증 토큰: 임의의 문자열 (웹훅 검증 과정에서 사용)
- messages 이벤트 구독

공개 웹훅 필요

WhatsApp은 외부에서 접근할 수 있는 HTTPS 웹훅 URL을 요구합니다. 역방향 프록시(nginx, Caddy)나 터널링 서비스(ngrok, Cloudflare Tunnel)로 Backend.AI GO의 Management API를 노출하세요.

Backend.AI GO에서 WhatsApp 연결¶

설정 > 채널 > WhatsApp으로 이동합니다.
다음을 입력합니다:
- 전화번호 ID: WhatsApp 전화번호 ID
- 액세스 토큰: 영구 액세스 토큰
- 웹훅 검증 토큰: Meta 개발자 포털에 설정한 검증 토큰
설정 검증을 클릭합니다.
연결을 클릭합니다.
Meta 개발자 포털에서 확인 및 저장을 클릭해 웹훅 검증을 진행합니다.

WhatsApp 트리거 동작¶

들어오는 다이렉트 메시지는 모두 봇을 트리거하고, 전화번호를 그룹에 추가하면 그룹 메시지도 처리할 수 있습니다.

JID 형식¶

WhatsApp 채팅 식별자는 wa:{phone_number} 형식을 사용합니다 (예: wa:15551234567).

연결된 채널 관리¶

채널 상태 보기¶

curl http://localhost:55765/api/v1/channels

응답:

{
  "channels": [
    {"name": "telegram", "connected": true, "statusMessage": "Connected"},
    {"name": "slack", "connected": true, "statusMessage": "Connected"},
    {"name": "discord", "connected": false, "statusMessage": "Not configured"},
    {"name": "whatsapp", "connected": false, "statusMessage": "Not configured"}
  ]
}

채널 연결 해제¶

설정 > 채널 > {채널 이름}으로 이동합니다.
연결 해제를 클릭합니다.

메시지 보내기¶

curl -X POST http://localhost:55765/api/v1/channels/messages \
  -H "Content-Type: application/json" \
  -d '{"chatJid": "tg:123456789", "content": "Hello from Backend.AI GO!"}'

메시지 기록 보기¶

# List all chats
curl http://localhost:55765/api/v1/channels/chats

# Get messages from a specific chat
curl "http://localhost:55765/api/v1/channels/chats/tg:123456789/messages?limit=50"

발신자 허용 목록¶

발신자 허용 목록은 에이전트와 상호작용할 수 있는 외부 사용자를 제한하는 장치인데, 허용 목록을 켜면 목록에 없는 발신자가 보낸 메시지는 아무 응답 없이 버려집니다.

Management API를 통한 설정¶

curl -X PUT http://localhost:55765/api/v1/channels/sender-allowlist \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entries": [
      {"chatJid": "tg:123456789", "label": "Alice"},
      {"chatJid": "slack:U01ABCDEF", "label": "Bob"}
    ]
  }'

동작¶

허용 목록 상태	수신 메시지	동작
비활성화	모든 메시지	처리 후 라우팅
활성화	목록에 있는 발신자	처리 후 라우팅
활성화	목록에 없는 발신자	조용히 삭제

다음 단계¶

채널-Squad 매핑: 메시지를 특정 Squad 그룹으로 라우팅
보안 모델: 보안 레이어 이해