Telegram 및 Matrix 설정

Telegram과 Matrix는 운영자들이 가장 먼저 선택하는 두 가지 채널입니다. Telegram은 별도의 인프라 없이 몇 분 만에 대화할 수 있는 봇을 제공하고, Matrix는 자체 호스팅 기반의 종단간 암호화(E2EE) 룸을 지원합니다. 이 가이드에서는 두 채널의 전체 설정 과정을 다룹니다. 토큰 및 설정, /bind 페어링 흐름, Telegram의 응답 스트리밍 및 반응, 그리고 Matrix E2EE가 실제로 응답을 전달하도록 하는 장치 ID, 복구 키, 기능 플래그 관련 세부 사항을 설명합니다. 마지막으로 #499 클래스의 “채널이 구성되었으나 응답이 없음” FAQ로 마무리합니다.

두 채널 모두 ~/.revka/config.toml의 [channels_config] 아래에서 구성하며, revka daemon 내부에서 실행됩니다. 채널을 처음 연결하는 경우라면, 먼저 메시징 채널 연결을 읽어 허용 목록 모델과 폴링 대 웹훅 방식의 차이를 확인하세요. Telegram과 Matrix 모두 공개 인바운드 포트가 필요하지 않습니다. 두 채널 모두 아웃바운드 연결을 통해 메시지를 가져오므로, NAT 뒤나 Raspberry Pi 환경에서도 동작합니다.

허용 목록은 기본적으로 차단합니다

모든 채널 허용 목록은 빈 상태로 시작하며, 이는 모두 차단을 의미합니다. 새로 추가된 채널은 연결되어 수신하지만, ID를 추가하기 전까지는 모든 사용자를 무시합니다. ["*"]는 임시 검증 용도로만 사용하고, 이후에는 명시적인 ID로 제한하세요.

Telegram

1. 봇 생성 및 구성

Telegram에서 @BotFather와 대화하고, /newbot을 실행한 뒤 발급된 토큰(123456:ABC-DEF... 형식)을 복사합니다. ~/.revka/config.toml에 채널을 추가합니다:

[channels_config.telegram]
bot_token = "123456:TELEGRAM-TOKEN"   # required, from @BotFather
allowed_users = ["*"]                 # tighten after testing
stream_mode = "off"                   # off | partial
draft_update_interval_ms = 1000       # edit throttle for partial mode
mention_only = false                  # only respond to @mentions in groups
interrupt_on_new_message = false      # cancel in-flight reply on a new message

필드	타입 / 값	기본값	설명
bot_token	string (필수)	—	@BotFather에서 발급받은 Bot API 토큰입니다.
allowed_users	list	[] (모두 차단)	Telegram 사용자 이름(@ 제외) 또는 숫자 사용자 ID, 혹은 "*"를 사용합니다.
stream_mode	"off" | "partial"	"off"	응답 전달 방식입니다(아래 참조).
draft_update_interval_ms	integer	1000	partial 모드에서 초안을 스트리밍할 때 수정 속도를 제한합니다.
mention_only	bool	false	그룹 채팅에서 @멘션이 있을 때만 응답합니다.
interrupt_on_new_message	bool	false	동일 발신자가 같은 채팅에서 새 메시지를 보내면 진행 중인 생성을 취소합니다.

데몬(또는 채널만)을 시작하고 봇에 메시지를 보냅니다:

revka daemon
# or, channels only:
revka channel start

TOML을 직접 편집하는 대신 CLI에서 채널을 추가할 수도 있습니다:

revka channel add telegram '{"bot_token":"123456:TELEGRAM-TOKEN","name":"my-bot"}'

참고

Telegram은 getUpdates를 통해 폴링 방식으로 동작하며, 공개 포트가 필요하지 않습니다. 메시지는 단어/줄바꿈 경계에서 4096자 제한에 맞게 자동으로 분할됩니다. 수신된 미디어(사진, 문서, 오디오, 비디오, 음성)는 ~/revka/downloads/에 다운로드됩니다. 발신 파일은 [IMAGE:...], [DOCUMENT:...], [VIDEO:...], [AUDIO:...], [VOICE:...]와 같은 마커를 사용합니다.

2. /bind 페어링

허용 목록이 기본적으로 모든 사용자를 차단하기 때문에, 봇에 메시지를 보낸 새 사용자는 거부됩니다. Revka는 운영자가 실행해야 할 정확한 명령어를 응답으로 전달합니다:

🔐 This bot requires operator approval.

Copy this command to operator terminal:
`revka channel bind-telegram 123456789`

After operator runs it, send your message again.

운영자는 터미널에서 해당 ID를 허용 목록에 추가합니다. 숫자 ID 또는 사용자 이름(@ 제외)을 사용할 수 있습니다:

revka channel bind-telegram 123456789
revka channel bind-telegram alice

또는 페어링이 활성화된 경우, 운영자가 제공하는 일회용 코드를 사용해 사용자가 채팅 내에서 직접 셀프 바인딩할 수 있습니다:

/bind 123456

유효한 코드를 입력하면 Revka는 발신자를 런타임 허용 목록에 추가하고, 설정 파일에 영구 저장한 뒤 ✅ Telegram account bound successfully.라고 응답합니다. 잘못된 코드는 거부되며, 반복된 잘못된 시도는 일시적인 잠금을 유발합니다(⏳ Too many invalid attempts. Retry in Ns.).

3. 스트리밍 및 반응

Telegram은 두 가지 응답 방식과 이모지 확인 반응을 지원합니다:

• stream_mode = "off" (기본값) — 생성이 완료되면 전체 응답을 한 번에 전송합니다.
• stream_mode = "partial" — Revka가 편집 가능한 초안을 게시하고, 토큰이 도착할 때마다 editMessageText를 통해 실시간으로 수정한 뒤 완성된 텍스트로 최종 확정합니다. draft_update_interval_ms(기본값 1000)는 초안 수정 빈도를 제한하여 Telegram 속도 제한을 준수합니다.

봇이 메시지를 처리하기 시작하면 ⚡️, 👌, 👀, 🔥, 👍 중 무작위로 선택된 확인 반응을 추가하여 발신자에게 메시지가 수신되었음을 알립니다.

허용된 Telegram 발신자는 다음 인채팅 런타임 명령어를 사용할 수 있습니다(발신자 범위, 데몬 재시작 불필요):

명령어	효과
/models	사용 가능한 프로바이더와 현재 선택을 표시합니다.
/models <provider>	이 발신자 세션의 프로바이더를 전환합니다.
/model	현재 모델을 표시합니다.
/model <model-id>	이 발신자 세션의 모델을 전환합니다.
/new	이 발신자의 대화 기록을 초기화하고 새로 시작합니다.

Matrix

Matrix는 Client-Server sync API를 통해 자체 홈서버의 룸(E2EE 룸 포함)에서 Revka를 실행합니다. 이 기능은 기능 플래그로 제어되므로, 아래 빌드 플래그를 확인하세요. 암호화의 안정성을 위해 고정된 장치 ID를 사용하는 것이 권장됩니다.

빌드 플래그: channel-matrix

기본 Revka 빌드에는 Matrix가 포함되지 않습니다. channel-matrix Cargo 기능을 사용하여 컴파일하세요:

cargo build --release --features channel-matrix
# combine with others as needed:
cargo build --release --features hardware,channel-matrix

[channels_config.matrix]가 존재하지만 해당 기능이 컴파일되지 않은 경우, revka channel list, revka channel doctor, revka channel start는 해당 빌드에서 채널이 의도적으로 건너뛰어졌음을 보고합니다. (Windows에서는 setup.bat --standard가 channel-matrix를 포함합니다.)

팁

설정 블록을 추가한 후 revka channel doctor로 바이너리에 Matrix 지원이 포함되어 있는지 확인하세요. “skipped for this build” 메시지가 표시되면 --features channel-matrix를 사용하여 다시 빌드해야 합니다.

Matrix 채널 구성

홈서버의 봇 계정과 그 액세스 토큰을 사용합니다. ~/.revka/config.toml에 추가합니다:

[channels_config.matrix]
homeserver = "https://matrix.example.com"   # required
access_token = "syt_..."                     # required
user_id = "@revka:matrix.example.com"        # recommended for E2EE
device_id = "DEVICEID123"                    # recommended for E2EE
room_id = "!room:matrix.example.com"         # or alias: #ops:matrix.example.com
allowed_users = ["*"]                        # tighten after testing
stream_mode = "partial"                      # off | partial | multi_message
draft_update_interval_ms = 1500              # higher than Telegram for E2EE overhead
multi_message_delay_ms = 800
recovery_key = ""                            # optional: cross-signing recovery

필드	타입 / 값	기본값	설명
homeserver	URL (필수)	—	홈서버 기본 URL입니다.
access_token	string (필수)	—	봇 계정의 토큰입니다.
user_id	string	—	봇 사용자 ID. E2EE 세션 복원에 권장됩니다.
device_id	string	—	고정 장치 ID. E2EE에 권장됩니다(아래 참조).
room_id	string	—	정식 룸 ID(!room:server) 또는 별칭(#name:server). 런타임에 해석됩니다.
allowed_rooms	list	[]	메시지를 수락할 추가 룸 ID 목록입니다.
allowed_users	list	[] (모두 차단)	Matrix 사용자 ID, 또는 "*"를 사용합니다.
stream_mode	"off" | "partial" | "multi_message"	"off"*	응답 전달 방식입니다.
draft_update_interval_ms	integer	1500	partial 모드에서의 수정 속도 제한(재암호화 및 페더레이션 지연으로 인해 Telegram보다 높게 설정).
multi_message_delay_ms	integer	800	multi_message 모드에서 문단 전송 사이의 지연 시간입니다.
recovery_key	string	""	교차 서명/키 백업 복구 키입니다(아래 참조).

* 온보딩 마법사는 새 Matrix 채널에 대해 partial을 기록합니다. stream_mode가 없는 기존 설정은 off로 기본 설정됩니다.

스트리밍 동작은 다른 채널과 동일합니다. partial은 편집 가능한 초안을 게시하고 Matrix m.replace 편집으로 업데이트합니다. multi_message는 문단(\n\n 기준 분리)을 별도 메시지로 전달하며, 코드 펜스는 분리하지 않습니다. 두 모드 모두 암호화된 룸과 암호화되지 않은 룸에서 동작하며, matrix-sdk가 E2EE를 투명하게 처리합니다.

보안: Matrix E2EE 채널

E2EE는 matrix-sdk가 처리하지만, 봇이 고정된 장치 ID를 가지고 룸의 암호화 키를 얻을 수 있을 때만 제대로 작동합니다. 가장 흔한 실패 사례인 “봇이 연결된 것처럼 보이지만 암호화된 룸에서 응답하지 않음” 문제는 거의 대부분 장치 ID 또는 키 공유 문제로 귀결됩니다.

device_id 및 교차 서명 recovery_key

Revka는 GET /_matrix/client/v3/account/whoami에서 자신의 ID를 읽으려 시도합니다. device_id가 반환되지 않으면, 재시작 시마다 새 장치가 등록되지 않도록 수동으로 설정하세요(새 장치가 계속 등록되면 키 공유와 검증이 깨집니다).

device_id를 확인하는 세 가지 방법:

1. whoami에서 확인 — 토큰이 장치 세션에 연결되어 있는 경우 가장 간단한 방법입니다:

   curl -sS -H "Authorization: Bearer $MATRIX_TOKEN" \
     "https://matrix.example.com/_matrix/client/v3/account/whoami"

   {"user_id": "@bot:example.com", "device_id": "ABCDEF1234"}

2. 비밀번호 로그인에서 확인 — whoami에서 device_id가 누락된 경우(관리자 API로 생성된 토큰):

   curl -sS -X POST "https://matrix.example.com/_matrix/client/v3/login" \
     -H "Content-Type: application/json" \
     -d '{"type":"m.login.password","user":"@bot:example.com","password":"...","initial_device_display_name":"Revka"}'

   반환된 access_token과 device_id 모두 설정에 사용합니다.

3. Element에서 확인 — 봇으로 로그인한 후, 설정 → 세션으로 이동하여 활성 세션의 장치 ID를 복사합니다.

두 값을 모두 설정에 지정하고, 재시작 시에도 device_id를 유지합니다:

[channels_config.matrix]
user_id = "@bot:example.com"
device_id = "ABCDEF1234"

복구 키를 사용하면 Revka가 서버 측 백업에서 룸 키와 교차 서명 시크릿을 자동으로 복원할 수 있습니다. 덕분에 장치 초기화, 암호화 저장소 삭제, 새 설치 후에도 이모지 인증이나 수동 키 공유 없이 복구가 가능합니다. Element에서 설정 → 보안 및 개인정보 보호 → 암호화 → 보안 백업으로 이동하여 복구 키를 확인하세요(백업이 설정되지 않은 경우 보안 키를 생성하면 됩니다. 형식은 EsTj 3yST y93F SLpB ...와 같습니다). 온보딩 시 추가하거나(마법사가 E2EE recovery key (or Enter to skip):를 묻습니다), 설정 파일을 직접 편집합니다:

[channels_config.matrix]
recovery_key = "EsTj 3yST y93F SLpB jJsz ..."

secrets.encrypt = true(기본값)인 경우, 다음 설정 저장 시 해당 값이 암호화됩니다. 유효한 키로 시작하면 다음 메시지를 확인할 수 있습니다:

Matrix E2EE recovery successful — room keys and cross-signing secrets restored from server backup.

일회용 키(OTK) 충돌

로그에 Matrix one-time key upload conflict detected; stopping sync to avoid infinite retry loop가 표시되면, 이전 장치를 등록 해제하지 않고 로컬 암호화 저장소가 초기화된 것입니다. Revka를 중지하고, 홈서버에서 기존 장치를 등록 해제(DELETE /_matrix/client/v3/devices/{id}, 대화형 인증 필요)한 뒤, 로컬 암호화 저장소(일반적으로 ~/.revka/state/matrix/)를 삭제합니다. 그런 다음 새 device_id와 access_token으로 다시 로그인하고, 설정을 업데이트한 뒤 재시작합니다. 장치를 먼저 등록 해제하지 않은 상태에서는 절대로 상태 디렉터리를 삭제하지 마세요.

디버그 로깅

E2EE 진단을 위해 Matrix 채널의 로그 레벨을 높입니다:

RUST_LOG=revka::channels::matrix=debug revka daemon
# even more detail from the SDK crypto layer:
RUST_LOG=revka::channels::matrix=debug,matrix_sdk_crypto=debug revka daemon

이를 통해 세션 복원 확인, 동기화별 완료 상태, OTK 충돌 상태, 헬스 체크 결과, 일시적/치명적 동기화 오류 분류 등을 확인할 수 있습니다.

E2EE FAQ (#499 클래스 “무응답”)

Matrix가 연결된 것처럼 보이고(검사를 통과하고, 오류가 없음) 봇이 응답하지 않는 경우, 다음 순서로 확인합니다:

1. 발신자 허용 목록. 발신자가 allowed_users에 허용되어 있는지 확인합니다. 빈 목록은 모든 사용자를 차단합니다. 진단을 위해 임시로 ["*"]로 설정해보세요.

2. 룸 멤버십. 봇 계정이 정확한 대상 룸에 참여해 있어야 합니다. 별칭(#...)을 사용한 경우, 예상하는 룸으로 올바르게 해석되는지 확인하세요.

3. 토큰 ID. 토큰이 봇 계정에 속하는지 확인합니다:

   curl -sS -H "Authorization: Bearer $MATRIX_TOKEN" \
     "https://matrix.example.com/_matrix/client/v3/account/whoami"

   반환된 user_id가 봇과 일치해야 합니다. device_id가 누락된 경우, 수동으로 설정하세요.

4. E2EE 키 공유. 암호화된 룸에서는 봇 장치가 신뢰할 수 있는 장치로부터 룸 키를 수신해야 합니다. 키가 없으면 암호화된 이벤트를 복호화할 수 없습니다. matrix_sdk_crypto::backups: ... no backup key was found 경고는 키 백업 복원이 아직 활성화되지 않았음을 의미합니다(일반적으로 치명적이지는 않지만, recovery_key를 설정하세요). 수신자에게 메시지가 “미검증”으로 표시되면, 신뢰할 수 있는 세션에서 봇 장치를 검증/서명하고 device_id를 유지하세요.

5. 신규 재시작. 설정을 변경한 후 데몬을 재시작하고, 기존 타임라인 기록이 아닌 새 메시지를 전송하세요:

   revka onboard --channels-only
   revka daemon

팁

Matrix 토큰을 로그 및 스크린샷에 노출하지 마세요. allowed_users는 허용 범위를 넓게 시작하여 명시적인 사용자 ID로 점차 좁히세요. 프로덕션 환경에서는 별칭 드리프트를 방지하기 위해 별칭 대신 정식 룸 ID를 사용하세요.

관련 페이지

메시징 채널 연결 채널 모델, 허용 목록 시맨틱, revka channel 명령어 안내입니다.

Mattermost 및 Nextcloud Talk 설정 자체 호스팅 팀 채팅 채널입니다.

Telegram, Discord 및 Slack 플랫폼별 전체 채널 카탈로그입니다.

Matrix, Mattermost 및 Nextcloud Talk 워크스페이스 채팅 채널 레퍼런스입니다.

revka channel 및 통합 channel add/bind/start/doctor CLI 레퍼런스입니다.

설정: 채널, 도구 및 통합 모든 채널 설정 키에 대한 설명입니다.