Telegram 채널 플러그인

Telegram 채널 플러그인은 Telegram Bot API를 통해 알림 메시지를 채팅으로 전송하는 alert_deliver 플러그인입니다. Core가 만든 렌더링 메시지를 전송 형식으로 전달합니다.

특징

• 봇 토큰과 채팅 ID 기반 전송을 지원합니다.
• plain, HTML, MarkdownV2 파싱 모드를 선택할 수 있습니다.
• 알림 끄기, 보호 콘텐츠, 제한 시간/재시도/백오프 설정을 제공합니다.
• 상태 점검에서 봇 토큰 검증과 테스트 채팅 메시지 전송을 구분합니다.

등록 전 확인

• BotFather에서 발급한 봇 토큰과 대상 채팅 ID를 준비합니다.
• 그룹/슈퍼그룹에서는 봇이 메시지를 보낼 권한을 가져야 합니다.
• 서식 모드를 사용할 경우 이스케이프 규칙을 확인합니다.

운영 팁

• 봇 토큰은 민감 정보이며 상태 점검/작업 응답에 노출하지 않습니다.
• 기본은 Core가 렌더링한 일반 텍스트를 사용하는 것이 가장 안전합니다.
• Telegram에는 범용 멱등성 키가 없으므로 중복 조사 기준은 Core 전송 세션입니다.

운영 화면

• 채널 설정은 봇 토큰, 채팅 ID, 파싱 모드, 알림/보호 콘텐츠, 제한 시간/재시도 정책을 다룹니다.
• Telegram은 별도 채널 화면을 제공하지 않습니다. 초안 진단은 등록/수정 폼과 테스트 결과 상세에서 확인합니다.
• 폼 보조 정보는 Telegram을 호출하지 않고 선택된 채팅 출처, 렌더링 메시지, 파싱 모드, 메시지 길이, 재시도 일정, 전송률 제한 힌트를 미리 보여줍니다.
• 연결 테스트는 봇 토큰 검증과 대상 채팅으로 테스트 메시지를 보내는 단계를 분리합니다.
• 전송 결과는 Telegram API 응답과 Core 전송 세션을 연결해 전송 실패 원인을 좁힙니다.

전달 방식과 제한

• Core가 만든 렌더링 텍스트를 Telegram 메시지로 변환해 전송합니다.
• HTML이나 MarkdownV2 파싱 모드는 이스케이프 문제로 실패할 수 있으므로, 중요한 운영 알림은 일반 텍스트가 가장 안정적입니다.
• Telegram 전송률 제한이나 그룹 권한 문제는 후속 제공자 정책이므로 채널 설정과 봇 권한을 함께 확인해야 합니다.
• 스레드/토픽 라우팅, 대화형 버튼, 파일 업로드, 봇 명령 업무 흐름은 현재 CE 채널 범위가 아닙니다.

대표 시나리오

• 메시지가 전송되지 않으면 봇 토큰 유효성, 채팅 ID, 그룹 권한, Telegram API 오류 코드를 확인합니다.
• 미리보기는 정상인데 메시지가 오지 않으면 연결 테스트를 먼저 실행하고, 이후 test_chat_id로 합성 테스트 메시지를 보냅니다.
• 서식 오류가 발생하면 파싱 모드를 일반 텍스트로 바꿔 재현성을 확인한 뒤 이스케이프를 조정합니다.
• 중복 메시지는 Core 전송 세션, 재시도 기록, Telegram API 제한 시간 여부를 함께 봅니다.