Telegram 추가하기

이 가이드는 고정된 문서를 그대로 옮긴 것이 아니라 이 사이트가 직접 쓴 글입니다. 위의 제품 커밋을 기준으로 작성했으며, 인용한 모든 제품 경로가 그 커밋에 실제로 있는지 확인했습니다.

provider 포털 단계는 각 provider의 공식 문서를 따릅니다. 문서 끝에 링크가 있으며, provider가 소유한 부분은 그 문서를 따르세요.

Telegram adapter는 Telegram Bot API와 직접 통신합니다. 봇 단위 getUpdates long polling을 쓰는데, 다른 무엇보다 먼저 알아야 할 결과가 하나 있습니다. 봇 토큰 하나에는 활성 poll 소유자가 정확히 하나만 있어야 합니다.

먼저 채팅 앱을 Virgo에 연결하기를 읽으세요. 이미 운영 중인 설치본에 adapter를 등록하는 것은 adapter add로 지원되므로, 아래 단계는 준비해 둘 서술자가 아니라 그 명령에서 끝납니다.

시작하기 전에

이미 운영 중이고 Hub에 닿을 수 있는 Virgo 설치본.
Telegram 봇과 그 토큰. Telegram 공식 문서를 따라 만드세요. Virgo가 봇을 대신 만들지 않습니다.
허용할 chat의 숫자 ID와, 새 발신자를 승인할 사람들의 숫자 사용자 ID.

polling이 봇 단위이므로, 같은 토큰에 두 번째 프로세스를 붙이지 마세요. 다른 Virgo 설치본이든 로컬 스크립트든 호스팅 서비스든 마찬가지입니다. poller가 둘이면 같은 업데이트를 두고 경합합니다.

봇 토큰을 비공개로 보관하기

credential은 부팅 시점에 해석되는 참조입니다. 구성에는 토큰이 절대 들어가지 않습니다.

필요한 서술자

모두 자리표시자입니다.

{
  "id": "telegram-main",
  "kind": "telegram",
  "session": "telegram-session",
  "vsp": "vsp:/your-account:your-space/telegram/bot",
  "credential": "credential:telegram/main",
  "targetVsp": "vsp:/your-account:your-space/your-repo/lead",
  "defaultChatId": 100000001,
  "accessNotificationChatId": 100000001,
  "allowedChatIds": "all",
  "artifactPort": "adapter-port:artifacts/main",
  "access": {
    "administrators": ["telegram.user:100000002"]
  }
}

targetVsp는 받아들여진 인바운드 메시지의 정본 목적지입니다. defaultChatId는 선택이며 기본 아웃바운드 대화가 됩니다. allowedChatIds는 "all"이거나 숫자 chat ID의 비어 있지 않은 고유 배열이고, 0이 아닌 안전한 정수를 최대 10,000개까지 받습니다. 새 비공개 채팅을 approval 모드로 발견하려면 "all"을 쓰세요.

accessNotificationChatId는 대기 중인 승인 요청을 공지하는 곳입니다. 접근이 approval 모드일 때, 즉 기본값일 때 필수이며, 없으면 설치가 서술자를 거부합니다. 범위가 허용하는 chat이어야 하고, defaultChatId도 설정했다면 둘이 같은 chat이어야 합니다.

어느 쪽을 고르든, adapter는 모든 인바운드 이벤트와 아웃바운드 명령을 실제 telegram.chat:<id> 대화에 묶고, 다른 chat을 가리키는 메시지 참조는 거부합니다.

접근과 관리자

Telegram은 approval이 기본입니다. 그래서 서술자에는 telegram.user:100000002 같은 안정적인 관리자 principal이 최소 하나 있어야 합니다. 사용자명과 표시 이름은 발신자를 인증하지 않습니다. 숫자 사용자 ID는 안정적이지만 사용자명은 그렇지 않습니다.

관리자는 /virgo-access approve <requestId> 또는 /virgo-access deny <requestId>로 대기 중인 요청을 결정합니다. 요청은 provider와 채널, tenant, 정본 principal 기준으로 중복이 제거되므로, 한 사람의 여러 비공개 대화가 각자의 대화·메시지 맥락은 유지한 채 하나의 요청으로 묶입니다. 관리자는 같은 설정 채널의 다른 대화에서도 그 요청을 결정할 수 있습니다.

사람이 아니라 채널인 발신자는 sender kind가 chat인 telegram.chat:<id>로 따로 표시됩니다.

이미 있는 설치본에 등록하기

새 설치본을 만들 때는 install이 --adapters와 --host-settings로 서술자를 받습니다. 설치본이 이미 있다면 지원되는 경로는 adapter add입니다.

adapter add --file /absolute/path/to/telegram.json
adapter list
adapter remove telegram-main

경로는 절대 경로여야 합니다. 이미 목록에 있는 id는 교체되지 않고 충돌로 거부되며, 새 항목만 준비되고, 그다음 목록 전체를 부팅이 검증하는 방식 그대로 검증합니다. 그래서 추가가 시작되지 않을 구성을 남길 수 없습니다. 서술자의 credentialBinding은 별도의 단계가 아니라 같은 작업 안에서 등록됩니다. adapter list는 각 항목이 지칭하는 자격 증명 참조와 함께 목록을 되읽으며, 비밀 자체는 보여 주지 않습니다.

다음 Host 시작에서 활성화됩니다. 동작 중인 Host는 부팅할 때 가지고 있던 adapter를 유지하고, 네이티브 agent 세션은 계속 돌아갑니다.

Telegram을 추가하려고 Hub를 다시 설치하지 마세요.

adapter가 할 수 있는 것과 없는 것

지원되는 조작은 일반 메시지, 인용 회신, 입력 중 표시, 현재 adapter 프로세스가 보낸 메시지 편집, 이모지 반응, 그리고 선택적인 문서 업로드입니다.

Telegram에는 입력 중 표시를 끄는 조작이 없습니다. 공용 Adaptive·Hero·Thumbnail 카드 형식도 지원하지 않습니다. effect-key 멱등성도, 일반적인 메시지 조회도 없어서, 잃어버렸거나 모호한 응답은 unknown으로 기록되고 그 adapter 인스턴스가 다시 제출하지 않습니다.

텍스트는 4,096 유니코드 코드포인트로 제한됩니다. poll 타임아웃은 1~50초입니다.

파일

artifact port가 해석되면 첨부는 양방향 모두 동작합니다. 아웃바운드에서는 문서를 보내기 전에 선언된 바이트 길이와 SHA-256을 검증하고, 인바운드에서는 Telegram에서 파일을 가져와 같은 port로 저장합니다.

서술자의 artifactPort는 선택입니다. 없으면 설치가 관리 artifact port로 대체하기 때문입니다. artifact 리더가 전혀 해석되지 않으면 기본 메시징은 부팅되고, 아웃바운드 첨부는 not_implemented로 보고되며, 인바운드 첨부는 조용히 사라지지 않고 설정되지 않았다는 이유로 거부됩니다.

문제 해결과 제거

업데이트가 멈추거나 두 번 옵니다. 거의 항상 토큰 하나에 poll 소유자가 둘인 경우입니다. 정확히 한 프로세스만 polling하게 하세요.
메시지는 받아들여졌는데 답이 없습니다. 발신자가 관리자 결정을 기다리는 중인지 확인하세요. approval이 기본값입니다.
문서가 전송되지 않거나 인바운드 파일이 거부됩니다. artifact port가 해석되는지 확인하세요. 설치가 관리 port로 대체하므로, 보통은 그 대체마저 해석되지 않은 경우입니다.
복구. 지속 커서는 인바운드 전달이 확인될 때만 전진하므로, 확인되지 않은 업데이트는 복구 후 다시 전달됩니다.
제거. BotFather로 토큰을 회수하고 자격 증명을 폐기하세요. 기존 설치본의 구성에서는 adapter remove <id>로 빼내며, Host는 다음 시작부터 그것을 제공하지 않습니다.

오늘 검증된 것

adapter 소스는 통합되어 있고 구성이 검증됩니다. 그것이 여러분의 계정에서의 실제 봇 검증은 아닙니다. 이미 있는 설치본에 등록하는 일은 정규 경로에서 Discord에 대해서만 수행되었고 거기서 Gateway READY까지 도달했습니다. agent가 Seat을 claim하는 것, 사람의 인바운드 메시지, 그에 상응하는 회신은 Telegram을 포함한 모든 provider에서 아직 검증되지 않았습니다. 가용성과 증거를 보세요.

프로토콜 참고 자료: Telegram Bot API.