Docs

Telegram Bot 연동

직접 만든 Telegram Bot을 Multica 에이전트에 연결해 DM, 그룹, forum topic, /issue에서 사용합니다.

Multica는 Telegram 공식 @BotFather에서 만든 Bot을 사용합니다. Bot 하나는 Multica 에이전트 하나에 연결됩니다. Telegram에서 각자 다른 Bot으로 보여야 하는 에이전트가 여럿이면 에이전트마다 Bot을 만드세요.

Telegram 연동은 커뮤니티가 유지관리합니다. 매 릴리스에 포함되지만 공식 지원 SLA는 제공되지 않습니다. 문제가 있으면 GitHub issues에 보고해 주세요.

시작하기 전에

  • 워크스페이스 owner 또는 admin만 Bot을 연결할 수 있습니다.
  • API 서버에서 https://api.telegram.org에 접속할 수 있어야 합니다.
  • @BotFather가 발급한 Bot token이 필요합니다. 비밀번호처럼 보호하세요.

Bot 연결

Bot 만들기

  1. @BotFather를 열고 /newbot을 보냅니다.
  2. 표시 이름과 bot으로 끝나는 username을 정합니다.
  3. HTTP API token을 복사합니다.
  4. 기본값으로 Group Privacy를 켜 둡니다. 가시 범위가 가장 좁은 구성으로, Telegram은 명령, 명시적 @멘션, Bot 메시지에 대한 답장만 Bot에 전달합니다. 끄면 Bot이 주변 그룹 대화를 컨텍스트로 활용할 수 있지만, 대신 그룹의 모든 메시지를 받게 됩니다. 자세한 내용은 Group Privacy가 Bot이 받는 메시지를 결정합니다를 참고하세요.

token을 태스크, 채팅, 로그, 코드 저장소에 남기지 마세요. 노출되었다면 @BotFather에서 폐기하고 새 token으로 다시 연결하세요.

에이전트에 연결하기

  1. Multica의 에이전트에서 에이전트를 선택하고 메신저를 엽니다.
  2. 메시지 채널 추가를 클릭한 뒤 Telegram을 선택합니다.
  3. Bot token을 붙여 넣고 연결을 클릭합니다.

Multica는 Telegram에서 Bot을 검증하고 long polling과 충돌하는 webhook이 없는지 확인한 뒤 token을 암호화해 저장하고 감독되는 getUpdates 연결을 시작합니다. 다른 에이전트나 워크스페이스에 연결된 Bot은 먼저 기존 연결을 해제해야 합니다.

처음 사용

멤버가 처음 Bot에 메시지를 보내면 일회용 Multica 계정 연결 링크를 받습니다. 같은 워크스페이스의 Multica 계정으로 로그인한 뒤 Telegram으로 돌아가 메시지를 다시 보내세요. 링크는 15분 후 만료되며, Bot에 다시 DM을 보내면 새 링크를 받을 수 있습니다.

그룹에는 자격 증명 역할을 하는 연결 링크를 공개하지 않습니다. Bot은 먼저 개인 채팅을 시작하라고 안내합니다.

현재 워크스페이스 멤버만 Bot을 사용할 수 있으며, 메시지마다 멤버 자격을 다시 확인합니다.

Telegram에서 작업 요청

개인 채팅

Bot을 열고 바로 텍스트를 보냅니다. @멘션은 필요 없습니다.

그룹과 forum topic

Bot을 그룹에 추가한 뒤 @멘션하거나 Bot 메시지에 직접 답장합니다. 수락된 메시지는 이어지는 Multica 대화에 남습니다. 일반 그룹은 각자 하나의 대화를 이어 가고, forum topic은 topic별로 분리됩니다.

명령

  • /new는 비어 있는 새 Multica Chat을 만들고 해당 Telegram 대화의 이후 메시지를 새 Chat으로 라우팅합니다. /new <메시지>를 보내면 그 메시지가 새 Chat의 첫 턴이 됩니다. 다른 멤버에게 답장하면서 Bot을 명시적으로 @멘션하면 선택한 인용 내용도 첫 턴에 포함됩니다.
  • /clear는 현재 Multica Chat을 유지하면서 다음 비어 있지 않은 메시지에 새 에이전트 컨텍스트를 적용합니다. /clear <메시지>를 보내면 그 메시지가 경계 이후의 첫 턴이 되며, 명시적으로 선택한 답장 인용도 유지됩니다.
  • /issue <제목>은 Multica 태스크를 만듭니다. 다음 줄은 선택 설명으로 사용됩니다. 제목 없이 보내면 사용법을 안내합니다.
  • 그룹에서는 /issue@your_bot 같은 Telegram 명령 접미사도 지원합니다.

응답과 지원되는 내용

Bot은 Telegram 메시지를 보내고 편집해 텍스트 응답을 스트리밍하며, 원래 메시지를 인용하고 forum topic을 유지합니다. 긴 응답은 Telegram 길이 제한에 맞춰 자동으로 나뉩니다. 에이전트가 작업하는 동안에는 같은 메시지에 현재 단계(명령 실행, 파일 읽기 등)와 경과 시간도 표시됩니다. 개인 채팅에서는 각 단계의 대상까지, 그룹에서는 작업 종류만 보여 줍니다. MULTICA_TELEGRAM_TOOL_PROGRESS(off, summary, detail)로 바꿀 수 있습니다.

이미지, 파일, 영상, 음성 메시지, 오디오는 caption을 메시지 본문으로 하여 같은 대화의 첨부 파일로 에이전트에 전달됩니다. 에이전트가 만든 파일은 응답 뒤에 채팅으로 다시 전송됩니다. 두 방향 모두 서버에 객체 스토리지가 필요합니다(아래 자체 호스팅 설정 참고).

연결 관리

설정 → 메신저에서 플랫폼별로 연결된 에이전트를 확인할 수 있습니다. 에이전트를 선택하면 상세 페이지의 메신저 섹션이 열립니다. 워크스페이스 owner/admin은 그곳의 Bot 관리 메뉴에서 연결을 해제할 수 있습니다. 해제하면 long polling과 이후 응답이 멈추지만 Multica 대화와 감사 기록은 유지됩니다.

자체 호스팅 설정

API 서버를 시작하기 전에 오래 유지할 32바이트 암호화 키를 설정합니다.

MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>

openssl rand -base64 32로 생성할 수 있습니다. 이 키를 잃어버리거나 교체하면 기존 Bot token을 복호화할 수 없어 Bot마다 다시 연결해야 합니다.

연결 링크는 MULTICA_APP_URL을 사용하며, 없으면 FRONTEND_ORIGIN으로 대체합니다. 만들어진 주소는 멤버가 접속할 수 있어야 합니다. 서버 네트워크나 proxy는 api.telegram.org에 대한 HTTPS 접속을 허용해야 하며, Go는 표준 HTTPS_PROXY / NO_PROXY 환경 변수를 읽습니다.

자주 묻는 문제

  • Bot 검증 실패: 먼저 서버 네트워크와 proxy를 확인합니다. Telegram이 token을 명시적으로 거부한 경우에만 재발급하세요.
  • webhook conflict: 연결 전에 이 Bot의 기존 webhook을 제거합니다. Telegram은 webhook과 getUpdates를 동시에 쓸 수 없습니다.
  • 409 polling conflict: 다른 Multica 인스턴스나 프로세스가 같은 Bot을 polling하고 있습니다. 그쪽을 중지하거나 환경별로 Bot을 분리합니다.
  • 그룹에서 답장 없음: Bot이 그룹에 있고 메시지가 @멘션 또는 Bot에 대한 답장인지 확인합니다.
  • 연결 링크 만료: Bot에 새 DM을 보내 최신 링크를 사용합니다.
  • 실행되지 않음: 에이전트가 보관 처리되었는지, 사용하는 런타임이 온라인인지 확인합니다.

다음 단계

  • 채팅 연동 — 플랫폼 비교와 대화·계정 연결 방식을 알아봅니다.
  • 에이전트와 대화 — Bot 메시지가 에이전트 실행이 되는 과정을 알아봅니다.
  • 태스크 — /issue가 만드는 작업 단위를 알아봅니다.

이 페이지에서